使用生成的 iOS SDK

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

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

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

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

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

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

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

  1. 将 Firebase 添加到您的 iOS 应用。

  2. 如需使用生成的 SDK，请在 Xcode 中将其配置为依赖项。

    在 Xcode 顶部导航栏中，依次选择 File > Add Package Dependencies > Add Local，然后选择包含生成的 Package.swift 的文件夹。

然后：

  1. 开发应用架构。

  2. 设置 SDK 生成：

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

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

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

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

生成 Swift 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 iOS SDK

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

获取连接器实例

连接器的代码将由 Data Connect 模拟器生成。如果您的连接器名称为 movies，且软件包为 movies（如 connector.yaml 中所指定），则通过调用以下代码检索连接器对象：

let connector = DataConnect.moviesConnector

实现查询和变更

借助连接器对象，您可以运行 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
  }
}

然后，您可以按如下方式制作影片：

let mutationResult = try await connector.createMovieMutation.execute(
  title: "Empire Strikes Back",
  releaseYear: 1980,
  genre: "Sci-Fi",
  rating: 5)

print("Movie ID: \(mutationResult.data.movie_insert.id)")

如需检索电影，您将使用查询引用。所有查询引用都是 Observable 发布者。根据配置的发布商（请参阅 connector.yaml)），它们要么支持 @Observable 宏（iOS 17 及更高版本），要么实现 ObservableObject 协议。如果未指定，则默认值为 iOS 17 及更高版本支持的 @Observable 宏。

在 SwiftUI 视图中，您可以使用查询 ref 的已发布 data 变量绑定查询结果，并调用查询的 execute() 方法来更新数据。data 变量将与 GQL 查询定义中定义的数据形状相匹配。

所有检索到的结果均符合 Decodable 协议。如果您在 GQL 提取中包含对象的主键，则这些对象也是 Identifiable，因此您可以在迭代器中使用它们。

struct ListMovieView: View {
    @StateObject private var queryRef = connector.listMoviesByGenreQuery.ref(genre: "Sci-Fi")
    var body: some View {
        VStack {
            Button {
                Task {
                    do {
                        try await refresh()
                    } catch {
                        print("Failed to refresh: \(error)")
                    }
                }
            } label: {
                Text("Refresh")
            }
                // use the query results in a view
            ForEach(queryRef.data?.movies ?? [], id: \.self.id) { movie in
                    Text(movie.title)
                }
            }
    }
    @MainActor
    func refresh() async throws {
        _ = try await queryRef.execute()
    }
}

查询还支持单次执行。

let resultData = try await DataConnect.moviesConnector.listMoviesByGenreQuery.execute(genre: "Sci-Fi")

处理对枚举字段的更改

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

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

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

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

弹性实现示例

生成的 SDK 会强制将未知值作为生成的枚举进行处理，因为生成的枚举包含 _UNKNOWN 值，并且 Swift 会强制执行详尽的 switch 语句。

do {
    let result = try await DataConnect.moviesConnector.listMovies.execute()
    if let data = result.data {
        for movie in data.movies {
            switch movie.aspectratio {
                case .ACADEMY: print("academy")
                case .WIDESCREEN: print("widescreen")
                case .ANAMORPHIC: print("anamorphic")
                case ._UNKNOWN(let unknownAspect): print(unknownAspect)
            }
        }
    }
} catch {
    // handle error
}

启用客户端缓存

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

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

generate:
  swiftSdk:
    outputDir: "../ios"
    package: "FirebaseDataConnectGenerated"
    clientCache:
      maxAge: 5s
      storage: persistent

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

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

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

  • storage：客户端 SDK 可配置为将响应缓存到 persistent 存储空间或 memory 中。缓存在 persistent 存储空间中的结果在应用重新启动后将保持不变。在 iOS SDK 中，默认值为 persistent。

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

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

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

    try await execute(fetchPolicy: .cacheOnly)

    try await execute(fetchPolicy: .serverOnly)

    为 iOS 应用设计原型并进行测试

    为客户端插桩以使用本地模拟器

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

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

    let connector = DataConnect.moviesConnector
// Connect to the emulator on "127.0.0.1:9399"
connector.useEmulator()

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

// Make calls from your app

    Data Connect SDK 中的数据类型

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

    Data Connect 类型 Swift
    字符串 字符串
    整数 整数
    浮点数 双精度型
    布尔值 布尔值
    UUID UUID
    日期 FirebaseDataConnect.LocalDate
    时间戳 FirebaseCore.Timestamp
    Int64 Int64
    不限 FirebaseDataConnect.AnyValue