使用生成的 Android SDK

借助 Firebase Data Connect 客户端 SDK，您可以直接从 Firebase 应用调用服务器端查询和突变。在设计部署到 Data Connect 服务的架构、查询和突变时，您可以并行生成自定义客户端 SDK。然后，将此 SDK 中的方法集成到您的客户端逻辑中。

正如我们在其他地方提到的，请务必注意，Data Connect查询和变异不是由客户端代码提交的，而是在服务器上执行的。相反，部署后，Data Connect 操作会像 Cloud Functions 一样存储在服务器上。这意味着您需要部署相应的客户端更改，以避免影响现有用户（例如，使用旧版应用的用户）。

因此，Data Connect 为您提供了一个开发者环境和工具，让您可以对服务器部署的架构、查询和突变进行原型设计。它还会在您进行原型设计时自动生成客户端 SDK。

当您对服务和客户端应用进行迭代更新后，服务器端和客户端更新即可部署。

客户端开发工作流程是什么？

如果您按照使用入门中的说明操作，则已了解 Data Connect 的整体开发流程。在本指南中，您可以详细了解如何从架构生成 Android SDK，以及如何处理客户端查询和突变。

您可以借助快速入门应用代码库学习客户端开发，并按照我们的 Android Codelab 构建功能齐全的 Data Connect 应用。

总而言之，若要在客户端应用中使用生成的 Android SDK，您需要先完成以下前提条件步骤：

1. 将 Firebase 添加到您的 Android 应用。
2. 在 Gradle 中将 Data Connect 配置为依赖项。
3. 添加 Kotlin Serialization Gradle 插件和 Gradle 依赖项。

然后：

1. 开发应用架构。

2. 设置 SDK 生成：

   • 使用 Data Connect VS Code 扩展程序中的向应用添加 SDK 按钮
   • 通过更新 connector.yaml

3. 初始化客户端代码并导入库。

4. 实现对查询和变更的调用。

5. 设置并使用 Data Connect 模拟器并进行迭代。

生成 Kotlin SDK

使用 Firebase CLI 在应用中设置生成的 Data Connect SDK。 init 命令应检测当前文件夹中的所有应用，并自动安装生成的 SDK。

firebase init dataconnect:sdk

在原型设计期间更新 SDK

如果您安装了 Data Connect VS Code 扩展程序，该扩展程序将始终保持生成的 SDK 为最新版本。

如果您不使用 Data Connect VS Code 扩展程序，可以使用 Firebase CLI 来确保生成的 SDK 保持最新状态。

firebase dataconnect:sdk:generate --watch

在构建流水线中生成 SDK

您可以在 CI/CD 构建流程中使用 Firebase CLI 生成 Data Connect SDK。

firebase dataconnect:sdk:generate

设置客户端代码

将 Data Connect 纳入您的客户端代码中

如需设置客户端代码以使用 Data Connect 和生成的 SDK，请先按照标准 Firebase 设置说明操作。

然后，将以下内容添加到 app/build.gradle.kts 中的 plugins 部分：

// The Firebase team tests with version 1.8.22; however, other 1.8 versions,
// and all newer versions are expected work too.
kotlin("plugin.serialization") version "1.8.22" // MUST match the version of the Kotlin compiler

然后，将以下内容添加到 app/build.gradle.kts 中的 dependencies 部分：

implementation(platform("com.google.firebase:firebase-bom:34.1.0"))
implementation("com.google.firebase:firebase-dataconnect")
implementation("com.google.firebase:firebase-auth") // Optional
implementation("com.google.firebase:firebase-appcheck") // Optional
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3") // Newer versions should work too
implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1") // Newer versions should work too

初始化 Data Connect Android SDK

使用您在设置 Data Connect 时所用的信息（全部可在 Firebase 控制台的“Data Connect”标签页中找到）初始化 Data Connect 实例。

ConnectorConfig 对象

SDK 需要连接器配置对象。

此对象是根据 dataconnect.yaml 中的 serviceId 和 location 以及 connector.yaml 中的 connectorId 自动生成的。

获取连接器实例

现在，您已设置配置对象，接下来可以获取 Data Connect 连接器实例。连接器的代码将由 Data Connect 模拟器生成。如果您的连接器名称为 movies，并且 Kotlin 软件包为 com.myapplication（如 connector.yaml 中所指定），则通过调用以下内容来检索连接器对象：

val connector = com.myapplication.MoviesConnector.instance

使用 Android SDK 中的查询和突变

借助连接器对象，您可以运行 GraphQL 源代码中定义的查询和变更。假设您的连接器定义了以下操作：

mutation createMovie($title: String!, $releaseYear: Int!, $genre: String!, $rating: Int!) {
  movie_insert(data: {
    title: $title
    releaseYear: $releaseYear
    genre: $genre
    rating: $rating
  })
}

query getMovieByKey($key: Movie_Key!) {
  movie(key: $key) { id title }
}

query listMoviesByGenre($genre: String!) {
  movies(where: {genre: {eq: $genre}}) {
    id
    title
  }
}

然后，您可以按如下方式创建和检索电影：

val connector = MoviesConnector.instance

val addMovieResult1 = connector.createMovie.execute(
  title = "Empire Strikes Back",
  releaseYear = 1980,
  genre = "Sci-Fi",
  rating = 5
)

val movie1 = connector.getMovieByKey.execute(addMovieResult1.data.key)

println("Empire Strikes Back: ${movie1.data.movie}")

您还可以检索多部电影：

val connector = MoviesConnector.instance

val addMovieResult2 = connector.createMovie.execute(
  title="Attack of the Clones",
  releaseYear = 2002,
  genre = "Sci-Fi",
  rating = 5
)

val listMoviesResult = connector.listMoviesByGenre.execute(genre = "Sci-Fi")

println(listMoviesResult.data.movies)

您还可以收集一个 Flow，该 Flow 仅在通过调用查询的 execute() 方法检索到新的查询结果时才会生成结果。

注意： 此流程不会实时更新。

val connector = MoviesConnector.instance

connector.listMoviesByGenre.flow(genre = "Sci-Fi").collect { data ->
  println(data.movies)
}

connector.createMovie.execute(
  title="A New Hope",
  releaseYear = 1977,
  genre = "Sci-Fi",
  rating = 5
)

connector.listMoviesByGenre.execute(genre = "Sci-Fi") // will cause the Flow to get notified

处理对枚举字段的更改

应用的架构可以包含枚举，这些枚举可供 GraphQL 查询访问。

随着应用设计发生变化，您可能会添加新的枚举支持值。例如，假设在应用的生命周期后期，您决定向 AspectRatio 枚举添加 FULLSCREEN 值。

在 Data Connect 工作流中，您可以使用本地开发工具来更新查询和 SDK。

不过，在您发布客户端的更新版本之前，已部署的旧客户端可能会出现故障。

弹性实现示例

生成的 SDK 会强制处理未知值，因为客户的代码必须解封装 EnumValue 对象，该对象对于已知的枚举值为 EnumValue.Known，对于未知值则为 EnumValue.Unknown。

val result = connector.listMoviesByAspectRatio.execute(AspectRatio.WIDESCREEN)
val encounteredAspectRatios = mutableSetOf<String>()

result.data.movies
  .mapNotNull { it.otherAspectRatios }
  .forEach { otherAspectRatios ->
    otherAspectRatios
      .filterNot { it.value == AspectRatio.WIDESCREEN }
      .forEach {
        when (it) {
          is EnumValue.Known -> encounteredAspectRatios.add(it.value.name)
          is EnumValue.Unknown ->
            encounteredAspectRatios.add("[unknown ratio: ${it.stringValue}]")
        }
      }
  }

println(
  "Widescreen movies also include additional aspect ratios: " +
    encounteredAspectRatios.sorted().joinToString()
)

为 Android 应用设计原型和进行测试

配置客户端以使用本地模拟器

您可以使用 Data Connect 模拟器，无论是在 Data Connect VS Code 扩展程序中还是在 CLI 中。

在应用中植入代码以连接到模拟器，这两种情况的操作相同。

val connector = MoviesConnector.instance

// Connect to the emulator on "10.0.2.2:9399"
connector.dataConnect.useEmulator()

// (alternatively) if you're running your emulator on non-default port:
connector.dataConnect.useEmulator(port = 9999)

// Make calls from your app

如需切换到生产资源，请注释掉用于连接到模拟器的行。

Data Connect SDK 中的数据类型

Data Connect 服务器表示常见和自定义 GraphQL 数据类型。在 SDK 中，这些内容表示如下。

数据连接类型	Kotlin
字符串	字符串
整数	Int（32 位整数）
浮点数	Double（64 位浮点数）
布尔值	布尔值
UUID	java.util.UUID
日期	com.google.firebase.dataconnect.LocalDate（在 16.0.0-beta03 之前为 java.util.Date）
时间戳	com.google.firebase.Timestamp
Int64	长
不限	com.google.firebase.dataconnect.AnyValue