使用生成的 Android SDK

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

正如我们在其他地方提到的那样,请务必注意,Data Connect 查询和更改不是由客户端代码提交并在服务器上执行的。相反,部署后,Data Connect 操作会像 Cloud Functions 一样存储在服务器上。这意味着,您需要部署相应的客户端更改,以免破坏现有用户(例如,在旧版应用中)。

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

迭代服务和客户端应用的更新后,服务器端和客户端更新均可部署。

生成 Kotlin SDK

与大多数 Firebase 项目一样,Firebase Data Connect 客户端代码的工作在本地项目目录中进行。Data Connect VS Code 扩展程序和 Firebase CLI 都是生成和管理客户端代码的重要本地工具。

SDK 生成选项的键值对应于您在初始化项目时生成的 dataconnect.yaml 文件中的多个条目。

初始化 SDK 生成

connector.yaml 中,添加 outputDirpackagepackageJsonDir(适用于 Web SDK)。
connectorId: movies
generate:
  kotlinSdk:
    outputDir: ../../../src/main/java/com/myapplication
    package: com.myapplication

outputDir 替换为将放置生成的代码的目录的路径;此路径是相对于包含 connector.yaml 文件的目录的路径。将 package 替换为要在生成的文件中使用的 Kotlin 软件包语句,或省略 package 以使用默认软件包。

在进行原型设计时更新 SDK

如果您使用 Data Connect VS Code 扩展程序及其 Data Connect 模拟器进行交互式原型设计,则在您修改用于定义架构、查询和更改的 .gql 文件时,系统会自动生成和更新 SDK 源文件。在热(重新)加载工作流中,这可能是一项非常有用的功能。

在其他情况下,如果您通过 Firebase CLI 使用 Data Connect 模拟器,则可以在 .gql 更新时设置手表,并自动更新 SDK 源代码。

或者,您也可以在 .gql 文件发生更改时使用 CLI 重新生成 SDK:

firebase dataconnect:sdk:generate --watch

生成用于集成和正式版本的 SDK

在某些情况下(例如准备项目源代码以提交 CI 测试),您可以调用 Firebase CLI 进行批量更新。

在这种情况下,请使用 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("com.google.firebase:firebase-dataconnect:16.0.0-beta01")
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1")
implementation("com.google.firebase:firebase-auth:23.1.0") // Optional
implementation("com.google.firebase:firebase-appcheck:18.0.0") // Optional

初始化 Data Connect Android SDK

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

ConnectorConfig 对象

SDK 需要连接器配置对象。

此对象由 dataconnect.yaml 中的 serviceIdlocation,以及 connector.yaml 中的 connectorId 自动生成。

获取连接器实例

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

val connector = com.myapplication.MoviesConnector.instance

运行查询和变更

借助连接器对象,您可以按照 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

原型设计和测试 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 中表示如下。

Data Connect 类型 Kotlin
字符串 字符串
整数 Int(32 位)
浮点数 双精度(64 位浮点数)
布尔值 布尔值
UUID java.util.UUID
日期 java.util.Date 中
时间戳 com.google.firebase.Timestamp
Int64
不限 com.google.firebase.dataconnect.AnyValue