使用產生的 Flutter SDK

Firebase SQL Connect 用戶端 SDK 可讓您直接從 Firebase 應用程式呼叫伺服器端查詢和變異。在設計要部署至 SQL Connect 服務的結構定義、查詢和變異時，您會同時產生自訂用戶端 SDK。接著，將這個 SDK 的方法整合至用戶端邏輯。

如先前所述，請務必注意，SQL Connect查詢和變動並非由用戶端程式碼提交，而是在伺服器上執行。相反地，部署時，SQL Connect 作業會儲存在伺服器上，例如 Cloud Functions。這表示您需要部署相應的用戶端變更，以免影響現有使用者 (例如使用舊版應用程式的使用者)。

因此，SQL Connect 提供開發環境和工具，讓您為伺服器部署的結構定義、查詢和變動建立原型。此外，在您設計原型時，系統也會自動產生用戶端 SDK。

反覆更新服務和用戶端應用程式後，伺服器端和用戶端更新都已準備就緒，可以部署。

用戶端開發工作流程為何？

如果您已按照「入門指南」操作，應該已瞭解 SQL Connect 的整體開發流程。本指南將詳細說明如何從結構定義產生 Flutter SDK，以及如何處理用戶端查詢和變動。

總之，如要在用戶端應用程式中使用產生的 Flutter SDK，請按照下列必要步驟操作：

1. 將 Firebase 新增至 Flutter 應用程式。
2. 安裝 flutterfire CLI dart pub global activate flutterfire_cli。
3. 執行 flutterfire configure。

接著：

1. 開發應用程式結構定義。

2. 設定 SDK 生成：

   • 在 SQL Connect VS Code 擴充功能中，使用「Add SDK to app」按鈕
   • 更新connector.yaml。

3. 初始化用戶端程式碼並匯入程式庫。

4. 實作查詢和異動呼叫。

5. 設定及使用 SQL Connect 模擬器，並反覆測試。

產生 Flutter SDK

使用 Firebase CLI 在應用程式中設定 SQL Connect 生成的 SDK。init 指令應會偵測目前資料夾中的所有應用程式，並自動安裝產生的 SDK。

firebase init dataconnect:sdk

在原型設計階段更新 SDK

如果已安裝 SQL Connect VS Code 擴充功能，系統會持續更新生成的 SDK。

如果不使用 SQL Connect VS Code 擴充功能，可以使用 Firebase CLI，讓產生的 SDK 保持最新狀態。

firebase dataconnect:sdk:generate --watch

在建構管道中產生 SDK

您可以使用 Firebase CLI，在 CI/CD 建構程序中生成 SQL Connect SDK。

firebase dataconnect:sdk:generate

設定用戶端程式碼

初始化 SQL Connect 應用程式

首先，請按照標準 Firebase 設定操作說明初始化應用程式。

接著，安裝 SQL Connect 外掛程式：

flutter pub add firebase_data_connect

初始化 SQL Connect Flutter SDK

使用設定 SQL Connect 時所用的資訊，初始化 SQL Connect 例項。如要查看這項資訊，請前往 Firebase 控制台的「Databases & Storage」(資料庫與儲存空間) >「SQL Connect」(SQL 連線) 頁面。

匯入程式庫

您需要匯入兩組項目，才能初始化用戶端程式碼：一般 SQL Connect 匯入項目，以及產生的特定 SDK 匯入項目。

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

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

在用戶端使用查詢

產生的程式碼會預先定義查詢參照。您只需要匯入並呼叫 execute 即可。

import 'generated/movies.dart';

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

呼叫 SDK 查詢方法

以下是使用這些動作快速鍵函式的範例：

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();
}

選填欄位

部分查詢可能包含選填欄位。在這種情況下，Flutter SDK 會提供建構工具方法，且必須另外設定。

舉例來說，呼叫 createMovie 時，rating 欄位為選用，因此您必須在建構函式中提供該欄位。

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

訂閱變更

請參閱「取得 SQL Connect 的即時更新」。

處理列舉欄位的變更

應用程式的結構定義可以包含列舉，並可透過 GraphQL 查詢存取。

隨著應用程式設計變更，您可能會新增列舉支援的值。舉例來說，假設您在應用程式生命週期的後續階段，決定在 AspectRatio 列舉中加入 FULLSCREEN 值。

在 SQL Connect 工作流程中，您可以使用本機開發人員工具更新查詢和 SDK。

不過，在您發布更新版用戶端之前，舊版部署的用戶端可能會中斷。

彈性導入範例

產生的 SDK 會強制處理不明的值。也就是說，用戶端程式碼必須將 EnumValue 物件解包為 Known 或 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}');
  }
}

啟用用戶端快取

SQL Connect 具有選用的用戶端快取功能，您可以編輯 connector.yaml 檔案來啟用這項功能。啟用這項功能後，產生的用戶端 SDK 會在本機快取查詢回應，這可減少應用程式發出的資料庫要求數量，並在網路可用性中斷時，讓應用程式中依賴資料庫的部分正常運作。

如要啟用用戶端快取，請在連接器設定中新增用戶端快取設定：

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

這項設定有兩個參數，皆為選用：

• maxAge：快取回應的最長保留時間，超過這個時間後，用戶端 SDK 就會擷取新值。範例：「0」、「30s」、「1h30m」。

  maxAge 的預設值為 0，表示系統會快取回應，但用戶端 SDK 一律會擷取最新值。只有在 CACHE_ONLY 指定為 execute()，且 subscribe() 傳回初始結果時，系統才會使用快取值。

• storage：用戶端 SDK 可設為將回應快取至 persistent 儲存空間或 memory。快取在 persistent 儲存空間中的結果，在應用程式重新啟動後仍會保留。指定 Android 或 iOS 時，預設值為 persistent。指定網路瀏覽器時，僅支援 memory 儲存空間。

更新連接器的快取設定後，請重新產生用戶端 SDK 並重新建構應用程式。完成後，execute() 和 subscribe() 會快取回應，並根據您設定的政策使用快取值。這通常會自動發生，您不需要採取任何額外步驟，但請注意下列事項：

• execute() 的預設行為如上所述：如果查詢結果已快取，且快取值不早於 maxAge，則使用快取值。這項預設行為稱為 PREFER_CACHE 政策。

  您也可以指定 execute() 的個別叫用，只提供快取值 (CACHE_ONLY)，或無條件從伺服器擷取最新值 (SERVER_ONLY)。

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

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

• 呼叫 subscribe() 時，無論 maxAge 設定為何，系統一律會立即傳回快取內容 (如有)。後續對 execute() 的呼叫會根據設定的 maxAge 通知事件監聽器。

在用戶端使用異動

變動的存取方式與查詢相同。

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

設計 Flutter 應用程式原型並進行測試

檢測用戶端以使用本機模擬器

無論是透過 SQL Connect VS Code 擴充功能或 CLI，您都可以使用 SQL Connect 模擬器。

無論是哪種情況，檢測應用程式以連線至模擬器的方式都相同。

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();

如要切換至正式環境資源，請將連線至模擬器的程式碼行註解排除。

Dart SDK 中的資料類型

SQL Connect 伺服器代表常見的 GraphQL 資料類型。在 SDK 中，這些狀態的表示方式如下。