第 8 章：云同步 (CloudKit Integration)

配置 CloudKit Schema

1. CloudKit Schema 基础概念

  • CloudKit 容器与记录类型
    SwiftData 通过 CloudKit 实现数据同步时，会自动将 @Model 类映射为 CloudKit 的 Record Type。每个模型的属性会转换为 CloudKit 记录字段。

    • 默认情况下，SwiftData 会为每个 @Model 生成对应的 CloudKit Schema。
    • 需确保应用的 Bundle Identifier 与 CloudKit 容器 ID 一致（通常在 Xcode 的 Signing & Capabilities 中配置）。

  • Schema 自动生成规则
    SwiftData 根据数据模型自动生成以下 CloudKit 元数据：

    • 基本类型（如 String、Int）映射为 CloudKit 原生字段类型。
    • 关系（@Relationship）通过 CKReference 实现关联。
    • 复杂类型（如 Codable 对象）会被序列化为 Data 类型存储。

2. 手动配置 CloudKit Schema

如果默认生成的 Schema 不满足需求，可通过以下方式自定义：

步骤 1：启用 CloudKit Dashboard

  1. 登录 Apple CloudKit Dashboard。
  2. 选择与项目匹配的 CloudKit 容器（通常为应用 Bundle ID）。

步骤 2：修改记录类型与字段

  • 添加/删除字段
    在 Schema 选项卡中，找到自动生成的记录类型（如 YourModel_ 前缀），可手动添加索引或调整字段类型。

    • 示例：为 TodoItem 模型的 dueDate 字段添加可查询索引。

  • 设置权限
    在 Security Roles 中配置记录的读写权限（如允许公开读取或仅限用户私有数据库）。

步骤 3：验证 Schema 兼容性

  • 确保 SwiftData 模型的每次修改与 CloudKit Schema 兼容：
    • 删除字段需通过迁移处理（参考第 6 章）。
    • 新增字段需标记为可选或提供默认值。

3. 代码中的 CloudKit 配置

在 SwiftData 初始化时，可通过 ModelConfiguration 指定 CloudKit 选项：

let container = try ModelContainer(
    for: TodoItem.self,
    configurations: ModelConfiguration(
        cloudKitDatabase: .private("iCloud.com.your.app") // 指定私有或公共数据库
    )
)

4. 常见问题与调试

  • Schema 同步失败
    错误场景：

    • 模型属性类型不被 CloudKit 支持（如复杂嵌套结构）。
    • 未启用 iCloud 和 CloudKit 能力。

    调试方法：

    1. 检查 Xcode 控制台的 [CloudKit] 日志。
    2. 使用 Console.app 过滤 com.apple.cloudkit 进程日志。

  • 性能优化

    • 对高频查询字段添加 CloudKit 索引。
    • 避免同步大型二进制数据（如 Data 类型超过 1MB）。

5. 示例：为 Todo 应用配置 Schema

假设有一个 TodoItem 模型：

@Model
class TodoItem {
    var title: String
    var isCompleted: Bool
    @Relationship var tags: [Tag]
}

在 CloudKit Dashboard 中需验证：

  1. 存在 TodoItem_ 和 Tag_ 记录类型。
  2. tags 关系字段显示为 CKReference 列表。
  3. 为 title 和 isCompleted 添加可查询索引。
Last Updated::