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

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

要从 CloudKit 私有数据库中获取 record ID 为 exampleID 的记录，请使用这个 Canopy 调用

let result = await Canopy().databaseAPI(usingDatabaseScope: .private).fetchRecords(with: [CKRecord.ID(recordName: "exampleID")])
switch result {
  case .success(let fetchRecordsResult):
    // handle fetchRecordsResult. Examine its foundRecords and notFoundRecordIDs properties.
  case .failure(let ckRecordError):
    // handle error
}

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

do {
  let result = try await Canopy().databaseAPI(usingDatabaseScope: .private).fetchRecords(…).get()
  // use result
} catch {
  // handle thrown error
}

Canopy 的设计旨在使你的代码可测试。你需要通过在你的大部分代码和功能中使用依赖注入模式来完成你的部分工作。你的大部分代码不应直接实例化 Canopy，而应从外部接收它。例如

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

  func someFeature() async {
    let databaseAPI = await canopy.getDatabaseAPI(usingDatabaseScope: .private)
    // call databaseAPI functions to
    // retrieve and modify records, zones, subscriptions …
  }
}

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

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(…)
  }
}

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

库提供了 Canopy 的主要功能和价值。Canopy 是主库，CanopyTestTools 帮助你构建测试。

Canopy 文档站点位于 https://canopy-docs.justtact.com，其中包含库的文档，以及关于库的动机和关于使用 CloudKit 的一些想法和最佳实践的信息。该文档由 DocC 从此仓库生成，也可以在 Xcode 中内联使用。

Thoughts 示例应用展示了在真实应用中使用 Canopy，并演示了现代多平台、多窗口应用开发的一些最佳实践。

Canopy

安装 Canopy

使用 Canopy

一行代码示例

使用抛出式返回类型

依赖注入以实现可测试性

使用 swift-dependency 进行依赖注入

了解 Canopy

库

文档

示例应用

作者和鸣谢