Canopy

Canopy 帮助你编写更好、更易测试的 CloudKit 应用程序。

安装 Canopy

Canopy 作为 Swift Package Manager 包分发。

如果你使用 Xcode UI 管理依赖项，请将 https://github.com/Tact/Canopy 添加为项目的依赖项。

如果你使用 SPM Package.swift，请添加以下内容：

dependencies: [
  .package(
    url: "https://github.com/Tact/Canopy",
    from: "0.2.0"
  )
]

使用 Canopy

一行示例

要从 CloudKit 私有数据库中获取具有记录 ID exampleID 的记录，请使用以下 Canopy 调用：

let result = await Canopy().databaseAPI(usingDatabaseScope: .private).fetchRecords(with: [CKRecord.ID(recordName: "exampleID")])
switch result {
  case .success(let fetchRecordsResult):
    // 处理 fetchRecordsResult。检查其 foundRecords 和 notFoundRecordIDs 属性。
  case .failure(let ckRecordError):
    // 处理错误
}

使用抛出返回类型

Canopy 将其所有 API 作为 async Result 提供。许多人更喜欢使用抛出式 API。使用 get() API 可以很容易地在调用站点将 Canopy API 调用转换为抛出式风格。对于上面的示例，请按照以下方法操作：

do {
  let result = try await Canopy().databaseAPI(usingDatabaseScope: .private).fetchRecords(…).get()
  // 使用结果
} catch {
  // 处理抛出的错误
}

依赖注入以提高可测试性

Canopy 旨在使你的代码可测试。你需要在大部分代码和功能中使用依赖注入模式来实现这一点。大多数代码不应直接实例化 Canopy，而应该从外部接收它。例如：

actor MyService {
  private let canopy: CanopyType
  init(canopy: CanopyType) {
    self.canopy = canopy
  }

  func someFeature() async {
    let databaseAPI = await canopy.getDatabaseAPI(usingDatabaseScope: .private)
    // 调用 databaseAPI 函数来
    // 检索和修改记录、区域、订阅等...
  }
}

在应用程序的实际使用中，你初始化并注入与 CloudKit 通信的实时 Canopy 对象。在独立测试功能时，你可以注入一个模拟的 Canopy 对象，它不与任何云服务通信，而是回放模拟响应。

阅读更多：使用 Canopy 创建可测试的 CloudKit 应用程序

使用 swift-dependency 进行依赖注入

Canopy 为 swift-dependencies 实现了 cloudKit 依赖键。如果你使用 swift-dependencies，可以这样使用 Canopy：

struct MyFeature {
  @Dependency(\.cloudKit) private var canopy
  func myFeature() async {
    let recordsResult = await canopy.databaseAPI(usingDatabaseScope: .private).fetchRecords(…)
  }
}

有关如何使用依赖项以及为预览和测试注入所需的 Canopy 依赖值的更多信息，请参阅 swift-dependencies 文档。