Menggunakan Flutter SDK yang dihasilkan

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

Seperti yang telah kami sebutkan di tempat lain, penting untuk diperhatikan bahwa SQL Connect kueri dan mutasi tidak dikirimkan oleh kode klien dan dieksekusi di server. Sebagai gantinya, saat di-deploy, SQL Connect operasi 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 dan alat pengembangan yang memungkinkan Anda membuat prototipe skema, kueri, dan mutasi yang di-deploy server. SQL Connect juga otomatis membuat SDK sisi klien saat Anda membuat prototipe.

Setelah Anda melakukan iterasi pembaruan pada aplikasi layanan dan klien, pembaruan sisi server dan klien siap di-deploy.

Apa yang dimaksud dengan 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 pembuatan Flutter SDK dari skema dan penggunaan kueri dan mutasi klien.

Singkatnya, untuk menggunakan Flutter SDK yang dibuat 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. Kembangkan skema aplikasi Anda.

2. Siapkan pembuatan SDK:

   • Dengan tombol Add SDK to app di ekstensi SQL Connect VS Code 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 dan lakukan iterasi.

Buat Flutter SDK

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

firebase init dataconnect:sdk

Memperbarui SDK saat membuat prototipe

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

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

firebase dataconnect:sdk:generate --watch

Membuat SDK dalam pipeline build

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

firebase dataconnect:sdk:generate

Menyiapkan kode klien

Melakukan inisialisasi aplikasi SQL Connect

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 (semua tersedia di tab SQL Connect konsol Firebase).

Mengimpor library

Ada dua kumpulan impor yang diperlukan untuk melakukan inisialisasi kode klien, impor umum SQL Connect dan impor SDK spesifik yang dibuat.

// 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 dibuat akan dilengkapi dengan Query Ref yang telah ditentukan sebelumnya. Yang perlu Anda lakukan hanyalah mengimpor dan memanggil execute di dalamnya.

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 akan mengekspos metode builder, dan harus ditetapkan secara terpisah.

Misalnya, kolom rating bersifat opsional saat memanggil createMovie, sehingga Anda harus memberikannya dalam fungsi builder.

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

Berlangganan perubahan

Lihat Mendapatkan update real-time dari SQL Connect.

Menangani perubahan pada kolom enumerasi

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

Saat desain aplikasi berubah, Anda dapat menambahkan nilai yang didukung enum 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 pengembangan lokal untuk memperbarui kueri dan SDK.

Namun, sebelum Anda merilis versi klien yang diperbarui, klien yang di-deploy sebelumnya mungkin akan rusak.

Contoh penerapan yang tangguh

SDK yang dibuat akan memaksa penanganan nilai yang tidak diketahui. Artinya, kode klien harus meng-unwrap 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 Anda dapat aktifkan dengan mengedit file connector.yaml. Jika fitur ini diaktifkan, SDK klien yang dibuat akan menyimpan respons kueri secara lokal dalam cache, 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 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 yang ditampilkan dari subscribe().

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

Setelah memperbarui konfigurasi caching konektor, buat ulang SDK klien dan bangun kembali aplikasi Anda. Setelah melakukannya, execute() dan subscribe() akan menyimpan respons dalam cache 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 ke pemanggilan individual execute() untuk hanya menayangkan nilai yang di-cache (CACHE_ONLY) atau untuk mengambil nilai baru dari server tanpa syarat (SERVER_ONLY).

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

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

• Saat Anda memanggil subscribe(), konten yang di-cache akan selalu langsung ditampilkan jika ada, terlepas dari setelan maxAge. Panggilan berikutnya ke execute() akan memberi tahu listener 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

Menginstrumentasi klien untuk menggunakan emulator lokal

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

Menginstrumentasi 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, beri komentar pada baris untuk terhubung ke emulator.

Jenis data di Dart SDK

Server SQL Connect mewakili jenis data GraphQL umum. Jenis data ini direpresentasikan di SDK sebagai berikut.