Menggunakan Flutter SDK yang dihasilkan

Dengan SDK klien Firebase SQL Connect, Anda dapat memanggil kueri dan mutasi sisi server langsung dari aplikasi Firebase. Anda membuat SDK klien kustom secara paralel saat mendesain skema, kueri, dan mutasi yang di-deploy ke layanan SQL Connect. Kemudian, Anda mengintegrasikan metode dari SDK ini ke dalam logika klien Anda.

Seperti yang telah kami sebutkan di bagian lain, perlu diperhatikan bahwa SQL Connect kueri dan mutasi tidak dikirimkan oleh kode klien dan dieksekusi di server. Sebagai gantinya, saat di-deploy, operasi SQL Connect disimpan di server seperti Cloud Functions. Artinya, Anda perlu men-deploy perubahan sisi klien yang sesuai untuk menghindari gangguan pada pengguna yang ada (misalnya, pada versi aplikasi yang lebih lama).

Itulah sebabnya SQL Connect menyediakan lingkungan pengembangan dan alat developer yang memungkinkan Anda membuat prototipe skema, kueri, dan mutasi yang di-deploy di server. Cloud Endpoints juga membuat SDK sisi klien secara otomatis, saat Anda membuat prototipe.

Setelah Anda mengulangi update pada aplikasi layanan dan klien, update sisi server dan klien siap di-deploy.

Bagaimana alur kerja pengembangan klien?

Jika Anda mengikuti Memulai, Anda akan diperkenalkan dengan alur pengembangan keseluruhan untuk SQL Connect. Dalam panduan ini, Anda akan menemukan informasi yang lebih mendetail tentang cara membuat Flutter SDK dari skema Anda serta menggunakan kueri dan mutasi klien.

Singkatnya, untuk menggunakan Flutter SDK yang dihasilkan di aplikasi klien, Anda harus mengikuti langkah-langkah prasyarat berikut:

1. Tambahkan Firebase ke aplikasi Flutter Anda.
2. Instal flutterfire CLI dart pub global activate flutterfire_cli.
3. Jalankan flutterfire configure.

Kemudian:

1. Mengembangkan skema aplikasi Anda.

2. Siapkan pembuatan SDK:

   • Dengan tombol Add SDK to app di ekstensi VS Code SQL Connect kami
   • Dengan memperbarui connector.yaml.

3. Lakukan inisialisasi kode klien dan impor library.

4. Terapkan panggilan ke kueri dan mutasi.

5. Siapkan dan gunakan emulator SQL Connect, lalu lakukan iterasi.

Membuat Flutter SDK

Gunakan Firebase CLI untuk menyiapkan SDK yang dihasilkan SQL Connect di aplikasi Anda. Perintah init akan mendeteksi semua aplikasi di folder saat ini dan menginstal SDK yang dihasilkan secara otomatis.

firebase init dataconnect:sdk

Mengupdate SDK saat membuat prototipe

Jika Anda telah menginstal ekstensi SQL Connect VS Code, ekstensi ini akan selalu memperbarui SDK yang dihasilkan.

Jika tidak menggunakan ekstensi VS Code SQL Connect, Anda dapat menggunakan Firebase CLI untuk terus memperbarui SDK yang dihasilkan.

firebase dataconnect:sdk:generate --watch

Membuat SDK di pipeline build

Anda dapat menggunakan Firebase CLI untuk membuat SDK SQL Connect dalam proses build CI/CD.

firebase dataconnect:sdk:generate

Menyiapkan kode klien

Melakukan inisialisasi aplikasi SQL Connect Anda

Pertama, lakukan inisialisasi aplikasi Anda menggunakan petunjuk penyiapan Firebase standar.

Kemudian, instal plugin SQL Connect:

flutter pub add firebase_data_connect

Melakukan inisialisasi SQL Connect Flutter SDK

Lakukan inisialisasi instance SQL Connect menggunakan informasi yang Anda gunakan untuk menyiapkan SQL Connect. Temukan informasi ini di halaman Databases & Storage > SQL Connect di Firebase console.

Mengimpor library

Ada dua set impor yang diperlukan untuk menginisialisasi kode klien Anda, impor SQL Connect umum dan impor SDK yang dihasilkan secara khusus.

// general imports
import 'package:firebase_data_connect/firebase_data_connect.dart';

// generated queries and mutations from SDK
import 'generated/movies.dart';

Menggunakan kueri di sisi klien

Kode yang dihasilkan akan dilengkapi dengan Referensi Kueri yang telah ditentukan. Anda hanya perlu mengimpor dan memanggil execute pada elemen tersebut.

import 'generated/movies.dart';

await MoviesConnector.instance.listMovies().execute();

Memanggil metode kueri SDK

Berikut adalah contoh penggunaan fungsi pintasan tindakan ini:

import 'generated/movies.dart';

function onBtnClick() {
  // This will call the generated Dart from the CLI and then make an HTTP request to the server.
  MoviesConnector.instance.listMovies().execute().then(data => showInUI(data)); // == MoviesConnector.instance.listMovies().ref().execute();
}

Kolom opsional

Beberapa kueri mungkin memiliki kolom opsional. Dalam kasus ini, Flutter SDK mengekspos metode builder, dan harus ditetapkan secara terpisah.

Misalnya, kolom rating bersifat opsional saat memanggil createMovie, jadi Anda perlu menyediakannya dalam fungsi builder.

await MoviesConnector.instance.createMovie( title: 'Empire Strikes Back', releaseYear: 1980, genre: 'Sci-Fi').rating(5).execute();

Berlangganan perubahan

Lihat Mendapatkan info terbaru secara real-time dari SQL Connect.

Menangani perubahan pada kolom enumerasi

Skema aplikasi dapat berisi enumerasi, yang dapat diakses oleh kueri GraphQL Anda.

Seiring perubahan desain aplikasi, Anda dapat menambahkan nilai yang didukung enum yang baru. Misalnya, bayangkan bahwa nanti dalam siklus proses aplikasi, Anda memutuskan untuk menambahkan nilai FULLSCREEN ke enum AspectRatio.

Dalam alur kerja SQL Connect, Anda dapat menggunakan alat developer lokal untuk memperbarui kueri dan SDK.

Namun, sebelum Anda merilis versi terbaru klien, klien lama yang di-deploy mungkin akan rusak.

Contoh implementasi yang tangguh

SDK yang dihasilkan memaksa penanganan nilai yang tidak diketahui. Artinya, kode klien harus membuka objek EnumValue menjadi Known atau Unknown.

final result = await MoviesConnector.instance.listMovies().execute();

if (result.data != null && result.data!.isNotEmpty) {
  handleEnumValue(result.data![0].aspectratio);
}

void handleEnumValue(EnumValue<AspectRatio> aspectValue) {
  if (aspectValue.value != null) {
    switch(aspectValue.value!) {
      case AspectRatio.ACADEMY:
        print('This movie is in Academy aspect');
        break;
      case AspectRatio.WIDESCREEN:
        print('This movie is in Widescreen aspect');
        break;
      case AspectRatio.ANAMORPHIC:
        print('This movie is in Anamorphic aspect');
        break;
      case AspectRatio.IMAX:
        print('This movie is in IMAX aspect');
    }
  } else {
    print('Unknown aspect ratio detected: ${aspectValue.stringValue}');
  }
}

Mengaktifkan caching sisi klien

SQL Connect memiliki fitur caching sisi klien opsional, yang dapat Anda aktifkan dengan mengedit file connector.yaml. Jika fitur ini diaktifkan, SDK klien yang dihasilkan akan meng-cache respons kueri secara lokal, yang dapat mengurangi jumlah permintaan database yang dibuat aplikasi Anda dan memungkinkan bagian aplikasi yang bergantung pada database berfungsi saat ketersediaan jaringan terganggu.

Untuk mengaktifkan caching sisi klien, tambahkan konfigurasi caching klien ke konfigurasi konektor Anda:

generate:
  javascriptSdk:
    outputDir: ../dart/
    package: "dataconnect_generated"
    clientCache:
      maxAge: 5s
      storage: memory

Konfigurasi ini memiliki dua parameter, keduanya bersifat opsional:

• maxAge: Usia maksimum respons yang di-cache sebelum SDK klien mengambil nilai baru. Contoh: "0", "30s", "1h30m".

  Nilai default untuk maxAge adalah 0, yang berarti respons di-cache, tetapi SDK klien akan selalu mengambil nilai baru. Nilai yang di-cache hanya akan digunakan jika CACHE_ONLY ditentukan ke execute() dan hasil awal ditampilkan dari subscribe().

• storage: SDK klien dapat dikonfigurasi untuk meng-cache respons di penyimpanan persistent atau di memory. Hasil yang di-cache di penyimpanan persistent akan tetap ada setiap kali aplikasi dimulai ulang. Jika menargetkan Android atau iOS, defaultnya adalah persistent. Saat menargetkan browser web, hanya penyimpanan memory yang didukung.

Setelah memperbarui konfigurasi caching konektor, buat ulang SDK klien dan build ulang aplikasi Anda. Setelah melakukannya, execute() dan subscribe() akan meng-cache respons dan menggunakan nilai yang di-cache sesuai dengan kebijakan yang Anda konfigurasi. Hal ini umumnya terjadi secara otomatis, tanpa langkah tambahan dari Anda; namun, perhatikan hal berikut:

• Perilaku default execute() adalah seperti yang dijelaskan di atas: jika hasil di-cache untuk kueri dan nilai yang di-cache tidak lebih lama dari maxAge, gunakan nilai yang di-cache. Perilaku default ini disebut kebijakan PREFER_CACHE.

  Anda juga dapat menentukan pemanggilan execute() satu per satu untuk hanya menyajikan nilai yang di-cache (CACHE_ONLY) atau untuk mengambil nilai baru tanpa syarat dari server (SERVER_ONLY).

  await queryRef.execute(fetchPolicy: QueryFetchPolicy.cacheOnly);
  

  await queryRef.execute(fetchPolicy: QueryFetchPolicy.serverOnly);
  

• Saat Anda memanggil subscribe(), konten yang di-cache akan selalu segera ditampilkan jika ada, terlepas dari setelan maxAge. Panggilan berikutnya ke execute() akan memberi tahu pemroses sesuai dengan maxAge yang dikonfigurasi.

Menggunakan mutasi di sisi klien

Mutasi dapat diakses dengan cara yang sama seperti kueri.

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();

Membuat prototipe dan menguji aplikasi Flutter Anda

Menginstrumentasikan klien untuk menggunakan emulator lokal

Anda dapat menggunakan emulator SQL Connect, baik dari ekstensi VS Code SQL Connect maupun dari CLI.

Melakukan instrumentasi aplikasi untuk terhubung ke emulator sama untuk kedua skenario.

import 'package:firebase_data_connect/firebase_data_connect.dart';
import 'generated/movies.dart';

MoviesConnector.instance.dataConnect
          .useDataConnectEmulator('127.0.0.1', 9399);

// Make calls from your app
QueryRef<ListMoviesData, void> ref = MoviesConnector.instance.listMovies.ref();

Untuk beralih ke resource produksi, jadikan baris untuk menghubungkan ke emulator sebagai komentar.

Jenis data di Dart SDK

Server SQL Connect mewakili jenis data GraphQL umum. Hal ini direpresentasikan dalam SDK sebagai berikut.