Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

使用生成的 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，您需要执行以下前提步骤：

将 Firebase 添加到您的 Flutter 应用。
安装 flutterfire CLI dart pub global activate flutterfire_cli。
运行 flutterfire configure。

然后：

开发应用架构。
设置 SDK 生成：
- 使用 SQL Connect VS Code 扩展程序中的将 SDK 添加到应用按钮
- 更新您的 connector.yaml。
初始化客户端代码并导入库。
实现对查询和变更的调用。
设置并使用 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 控制台的数据库和存储 > SQL Connect 页面中找到此信息。

导入库

初始化客户端代码需要两组导入：常规 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 模拟器，无论是通过 SQL Connect VS Code 扩展程序还是通过 CLI。

在这两种情况下，对应用进行插桩以连接到模拟器的方式相同。

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 中表示如下。

SQL Connect 类型	Dart
时间戳	firebase_data_connect.Timestamp
Int（32 位）	整数
日期	DateTime
UUID	字符串
Int64	整数
浮点数	double
布尔值	布尔值
不限	firebase_data_connect.AnyValue

使用生成的 Flutter SDK 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。