使用生成的 Android SDK

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

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

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

当您对服务和客户端应用进行迭代更新后，服务器端和客户端更新都已准备好进行部署。

客户端开发工作流程是怎样的？

如果您已阅读使用入门，那么您已经了解了 SQL Connect 的整体开发流程。在本指南中，您将详细了解如何根据架构生成 Android SDK，以及如何使用客户端查询和变更。

总而言之，如需在客户端应用中使用生成的 Android SDK，您需要执行以下前提步骤：

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

然后：

1. 开发应用架构。

2. 设置 SDK 生成：

   • 使用 SQL Connect VS Code 扩展程序中的将 SDK 添加到应用按钮
   • 更新您的 connector.yaml

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

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

5. 设置并使用 SQL Connect 模拟器，然后进行迭代。

生成 Kotlin 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 纳入您的客户端代码

如需设置客户端代码以使用 SQL 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:35.0.1"))
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

初始化 SQL Connect Android SDK

使用您在设置 SQL Connect 时所用的信息初始化 SQL Connect 实例。您可以在 Firebase 控制台的数据库和存储 > SQL Connect 页面中找到此信息。

ConnectorConfig 对象

SDK 需要连接器配置对象。

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

获取连接器实例

设置好配置对象后，获取 SQL Connect 连接器实例。连接器的代码将由 SQL 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，它仅在通过调用查询的 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

订阅实时变更

请参阅从 SQL Connect 获取实时更新。

处理对枚举字段的更改

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

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

在 SQL 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()
)

启用客户端缓存

SQL Connect 具有可选的客户端缓存功能，您可以通过修改 connector.yaml 文件来启用该功能。启用此功能后，生成的客户端 SDK 将在本地缓存查询响应，这可以减少应用发出的数据库请求数量，并使应用中依赖数据库的部分在网络可用性中断时仍能正常运行。

如需启用客户端缓存，请将客户端缓存配置添加到连接器配置中：

generate:
  kotlinSdk:
    outputDir: "../android"
    package: "com.google.firebase.dataconnect.generated"
    clientCache:
      maxAge: 5s
      storage: persistent

此配置有两个参数，均为可选参数：

• maxAge：在客户端 SDK 提取新值之前，缓存响应的最长存在时间。示例：“0”“30s”“1h30m”。

  maxAge 的默认值为 0，这意味着响应会被缓存，但客户端 SDK 始终会提取新值。仅当 CACHE_ONLY 指定为 execute() 时，系统才会使用缓存的值。

• storage：客户端 SDK 可配置为在 persistent 存储空间或 memory 中缓存响应。缓存在 persistent 存储空间中的结果会在应用重启后保留。在 Android SDK 中，默认值为 persistent。

更新连接器的缓存配置后，请重新生成客户端 SDK 并重新构建应用。完成这些操作后，execute() 将根据您配置的政策缓存响应并使用缓存的值。这通常会自动发生，您无需执行任何其他步骤；但请注意以下事项：

• execute() 的默认行为如上所述：如果查询结果已缓存，且缓存值不早于 maxAge，则使用缓存值。此默认行为称为 PREFER_CACHE 政策。

  您还可以指定 execute() 的各个调用，以仅提供缓存值 (CACHE_ONLY) 或无条件地从服务器提取新值 (SERVER_ONLY)。

  val queryResult = queryRef.execute(QueryRef.FetchPolicy.CACHE_ONLY)
  

  val queryResult = queryRef.execute(QueryRef.FetchPolicy.SERVER_ONLY)
  

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

  对客户端进行插桩，以使用本地模拟器

  您可以使用 SQL Connect 模拟器，无论是通过 SQL 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
  
  

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

  SQL Connect SDK 中的 SQL 类型

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

  SQL Connect 类型	Kotlin
  字符串	字符串
  整数	Int（32 位整数）
  浮点数	双精度（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