# CloudKit 参考 **用途**：基于数据库的 iCloud 存储和同步的综合 CloudKit 参考 **可用性**：iOS 10.0+（基本）、iOS 17.0+（CKSyncEngine）、iOS 17.0+（SwiftData 集成） **上下文**：通过 CKSyncEngine（WWDC 2023）或 SwiftData 集成进行现代 CloudKit 同步 ## 何时使用此技能在以下情况下使用此技能： * 实现结构化数据同步到iCloud * 在 SwiftData+CloudKit、CKSyncEngine 或原始 CloudKit API 之间进行选择 * 设置公共/私有/共享数据库 * 实施冲突解决 * 调试CloudKit同步问题 * 监控CloudKit性能 **不适用于**：简单文件同步（使用 `axiom-icloud-drive-ref` 代替） ## 概述 **CloudKit 用于结构化数据同步**（具有关系的记录），而不是简单的文件同步。三种现代方法： 1. **SwiftData + CloudKit**（最简单，iOS 17+） 2. **CKSyncEngine**（自定义持久性，iOS 17+，WWDC 2023） 3. **原始 CloudKit API**（最大程度的控制，更复杂） ** ** ## 方法一：SwiftData + CloudKit（推荐） **何时使用**：具有 SwiftData 模型的 iOS 17+ 应用程序 **限制**： * 仅私有数据库（无公共/共享） * 自动同步（较少控制） * SwiftData 约束适用 // ✅ 正确：SwiftData 与 CloudKit 同步导入 SwiftData @模型类任务{ var 标题：字符串 var isCompleted: Bool var dueDate: 日期 init(标题: 字符串, isCompleted: Bool = false, dueDate: 日期) { self.title = 标题 self.isCompleted = 已完成 self.dueDate = 截止日期 } } // 配置CloudKit容器让容器 = 尝试 ModelContainer( 对于：Task.self，配置：模型配置（ cloudKitDatabase: .private("iCloud.com.example.app") ）） // 就是这样！同步自动发生 **所需权利**： * iCloud 功能 * CloudKit容器 **使用 `axiom-swiftdata` 技能获取 SwiftData 详细信息** ** ** ## 方法 2：CKSyncEngine（现代，WWDC 2023） **何时使用**：带有云同步的自定义持久性（SQLite、GRDB、JSON） **相对于原始 CloudKit 的优势**： * 自动管理获取/上传周期 * 处理冲突 * 管理账户变更 * 推荐使用手动 CKDatabase 操作 // ✅ 正确：CKSyncEngine 设置导入CloudKit 类 SyncManager { 让同步引擎：CKSyncEngine init() 抛出 { 让配置 = CKSyncEngine.Configuration( 数据库：CKContainer.default().privateCloudDatabase，状态序列化：loadSyncState(), 代表：自己）同步引擎 = 尝试 CKSyncEngine(配置) } // 实现委托方法 } 扩展 SyncManager: CKSyncEngineDelegate { // 处理事件 func handleEvent(_ event: CKSyncEngine.Event,syncEngine: CKSyncEngine) async { 切换事件{ case.stateUpdate(让stateUpdate): saveSyncState(stateUpdate.stateSerialization) case .accountChange(让改变): 处理AccountChange（更改） case .fetchedDatabaseChanges（让更改）：应用数据库更改（更改） case .fetchedRecordZoneChanges（让更改）：应用记录更改（更改） case .sentRecordZoneChanges（让更改）：处理已发送更改（更改）案例 .willFetchChanges、.didFetchChanges、 .willSendChanges、.didSendChanges： // 可选的生命周期事件打破 @未知默认值：打破 } } // 下一批要发送的更改 func nextRecordZoneChangeBatch( _上下文：CKSyncEngine.SendChangesContext，同步引擎：CKSyncEngine ) 异步 -> CKSyncEngine.RecordZoneChangeBatch？ { // 返回待处理的本地更改让pendingChanges = getPendingLocalChanges() 返回 CKSyncEngine.RecordZoneChangeBatch( 待定保存：待定更改，要删除的记录ID：[] ） } } **关键概念**： * **状态序列化** ：在应用程序启动之间保留同步状态 * **事件** ：委托接收更改事件 * **批次** ：您提供待处理的更改，引擎上传它们 * **自动冲突解决**：引擎处理基本冲突 ** ** ## 方法 3：原始 CloudKit API（旧版） **何时使用** ：仅当 CKSyncEngine 不适合时（罕见） **核心类型**： * `CKContainer` - 入口点 * `CKDatabase` - 公共/私有/共享范围 * `CKRecord` — 单独的数据记录 * `CKRecordZone` - 逻辑分组 * `CKAsset` — 二进制文件存储 ### 基本操作 // ✅ 容器和数据库让容器= CKContainer.default() 让 privateDatabase = 容器.privateCloudDatabase 让 publicDatabase = 容器.publicCloudDatabase // ✅ 创建记录让记录 = CKRecord(recordType: "任务") record["title"] = "购买杂货" 记录[“已完成”] = false 记录[“到期日期”] = 日期() // ✅ 保存记录尝试等待 privateDatabase.save(record) // ✅ 获取记录让 recordID = CKRecord.ID(recordName: "task-123") 让 fetchedRecord = 尝试等待 privateDatabase.record(for: recordID) // ✅ 查询记录让谓词 = NSPredicate(格式：“isCompleted == NO”) 让查询= CKQuery（记录类型：“任务”，谓词：谓词） let (matchResults, _) = 尝试等待 privateDatabase.records(匹配: 查询) 对于 matchResults 中的结果 { if case .success(let record) = result.1 { print("任务：\(记录["标题"]为？字符串??"")") } } // ✅ 删除记录尝试等待 privateDatabase.deleteRecord(withID: recordID) ### 更新记录 // ✅ Fetch-then-modify-then-save（防止 serverRecordChanged 错误）让记录 = 尝试等待 privateDatabase.record(for: recordID) record["title"] = "更新的标题" 记录[“已完成”] = true 尝试等待 privateDatabase.save(record) // ✅ 批量修改（一次操作保存+删除）让操作 = CKModifyRecordsOperation( 记录保存：[更新记录1，更新记录2]， recordIDsToDelete: [已删除ID] ） operation.perRecordSaveBlock = { recordID, 结果切换结果{ case .success: print("已保存：\(recordID)") case .failure(let error): print("失败：\(recordID) — \(error)") } } 尝试等待 privateDatabase.add(操作) ### 冲突解决 // ✅ 处理与 savePolicy 的冲突让操作 = CKModifyRecordsOperation( 记录保存：[记录]，要删除的记录 ID：nil ） // 仅当服务器版本不变时才保存操作.savePolicy = .ifServerRecordUnchanged // OR: 始终覆盖服务器 operation.savePolicy = .changedKeys // 仅更改的字段 operation.modifyRecordsResultBlock = { 结果切换结果{ 案例.成功：打印（“已保存”） case .failure（让错误为CKError）： if error.code == .serverRecordChanged { // 冲突 - 手动合并让 serverRecord = error.serverRecord 让 clientRecord = error.clientRecord 让合并= mergeRecords（服务器：serverRecord，客户端：clientRecord） // 重试合并记录 } } } privateDatabase.add(操作) ** ** ## 数据库范围范围 |无障碍 | SwiftData 支持 |使用案例 ---|---|---|--- **私人** |仅限用户| ✅ 是的 |个人用户数据 **公开** |所有用户 | ❌ 否 |共享/公共内容 **共享** |受邀用户| ❌ 否 |协作 ### 私有数据库 // ✅ 私有数据库（最常见）让 privateDB = CKContainer.default().privateCloudDatabase // 用户必须登录 iCloud // 跨用户设备同步数据 // 对其他用户不可见 ### 公共数据库 // ✅ 公共数据库（用于共享内容）让 publicDB = CKContainer.default().publicCloudDatabase // 所有应用程序用户都可以访问 // 即使未经身份验证的用户也可以读取 // 写入需要验证 // 用于：排行榜、公共内容、发现 ### 共享数据库 // ✅ 共享数据库（协作）让sharedDB = CKContainer.default().sharedCloudDatabase // 用于基于 CKShare 的协作 // 受邀进入特定记录区域的用户 // 用于：共享文档、团队数据 ** ** ## CloudKit 资产（文件） // ✅ 将文件存储为 CKAsset let imageURL = saveImageToTempFile(image) // 必须是文件 URL 让 asset = CKAsset(fileURL: imageURL) 让记录 = CKRecord(recordType: "照片") 记录[“图像”] = 资产记录[“标题”] =“日落” 尝试等待 privateDatabase.save(record) // ✅ 检索资产让 fetchedRecord = 尝试等待 privateDatabase.record(for: recordID) 如果让 asset = fetchedRecord["image"] 为？ CKAsset, 让 fileURL = asset.fileURL { 让 imageData = 尝试 Data(contentsOf: fileURL) 让图像 = UIImage(数据: imageData) } **重要**：CKAsset 需要 **文件 URL**，而不是数据。首先将数据写入临时文件。 ** ** ## CloudKit 控制台（监控 - WWDC 2024） ### 开发者通知设置警报： * 架构变更 * 超出配额 * 错误率高 * 自定义阈值 ### 遥测监控： * 请求数 * 错误率 * 延迟（p50、p95、p99） * 带宽使用情况 ### 日志查看： * 个人要求 * 错误详细信息 * 性能瓶颈 **访问**： ** ** ## 常见模式 ### 模式 1：初始同步 // ✅ 首次启动时获取所有记录 func PerformInitialSync() 异步抛出 { let predicate = NSPredicate(value: true) // 所有记录让查询= CKQuery（记录类型：“任务”，谓词：谓词） let (结果, _) = 尝试等待 privateDatabase.records(匹配: 查询) 对于结果中的结果{ if case .success(let record) = result.1 { 保存到本地数据库（记录） } } } ### 模式 2：增量同步 // ✅ 使用 CKServerChangeToken 进行增量获取 func fetchChanges(since token: CKServerChangeToken?) async throws { 让 zoneID = CKRecordZone.ID(zoneName: "任务") 让配置 = CKFetchRecordZoneChangesOperation.ZoneConfiguration( previousServerChangeToken：令牌）让操作 = CKFetchRecordZoneChangesOperation( recordZoneIDs: [zoneID], 配置按记录区域ID：[区域ID：配置] ） operation.recordWasChangedBlock = { recordID, 结果 if case .success(让记录) = 结果 { 更新本地数据库（带有：记录） } } operation.recordWithIDWasDeletedBlock = { recordID, _ in 从本地数据库删除（记录ID） } operation.recordZoneFetchResultBlock = { zoneID, 结果 if case .success(let (token, _, _)) = 结果 { saveChangeToken(token) // 用于下次获取 } } 尝试等待 privateDatabase.add(操作) } ** ** ## 权利 Xcode 中所需的权利： com.apple.developer.icloud-services <数组> <字符串>云套件 com.apple.developer.icloud-container-identifiers <数组> iCloud.com.example.app **设置**： 1. Xcode → 目标 → 签名和功能 2.“+能力”→iCloud 3.勾选“CloudKit” 4. 选择或创建容器 ** ** ## 订阅（推送通知） ### 数据库订阅 // ✅ 获取私有数据库中任何更改的通知让订阅 = CKDatabaseSubscription(subscriptionID: "all-changes") 让 notificationInfo = CKSubscription.NotificationInfo() notificationInfo.shouldSendContentAvailable = true // 静默推送订阅.notificationInfo = notificationInfo 尝试等待 privateDatabase.save(订阅) ### 查询订阅 // ✅ 当与查询匹配的记录发生更改时收到通知让谓词 = NSPredicate(格式：“优先级 > 3”) 让订阅 = CKQuerySubscription( 记录类型：“任务”，谓词：谓词， subscriptionID: "高优先级任务", 选项：[.firesOnRecordCreation、.firesOnRecordUpdate、.firesOnRecordDeletion] ）让 notificationInfo = CKSubscription.NotificationInfo() notificationInfo.alertBody = "高优先级任务已更改" notificationInfo.shouldBadge = true 订阅.notificationInfo = notificationInfo 尝试等待 privateDatabase.save(订阅) ### 区域订阅 // ✅ 获取特定区域的任何变化通知让 zoneID = CKRecordZone.ID(zoneName: "任务") 让订阅 = CKRecordZoneSubscription( 区域ID：区域ID，订阅ID：“任务区域” ）让 notificationInfo = CKSubscription.NotificationInfo() notificationInfo.shouldSendContentAvailable = true 订阅.notificationInfo = notificationInfo 尝试等待 privateDatabase.save(订阅) ### 处理推送通知 // 在 AppDelegate 中功能应用程序（_应用程序：UIApplication， didReceiveRemoteNotification userInfo: [AnyHashable: Any]) async -> UIBackgroundFetchResult { 让通知 = CKNotification(fromRemoteNotificationDictionary: userInfo) if notification.subscriptionID == "all-changes" { 试试？等待 fetchChanges（自：savedChangeToken）返回.newData } 返回.noData } ** ** ## 分享记录 ### 创建共享 // ✅ 与其他用户共享记录让记录 = 尝试等待 privateDatabase.record(for: recordID) // 记录必须位于自定义区域（非默认区域）让共享 = CKShare(rootRecord: 记录) share[CKShare.SystemFieldKey.title] = "共享任务列表" share.publicPermission = .none // 仅限邀请 // 保存记录并一起分享让操作 = CKModifyRecordsOperation( RecordsToSave: [记录、分享], 要删除的记录 ID：nil ）尝试等待 privateDatabase.add(操作) ### 呈现分享界面导入CloudKit 导入 UIKit // ✅ UIKit 共享控制器让共享控制器= UICloudSharingController（共享：共享，容器：容器）共享控制器.delegate = self 存在（共享控制器，动画：true） // 委托方法扩展 ViewController: UICloudSharingControllerDelegate { func cloudSharingController(_ csc: UICloudSharingController, failedToSaveShareWithError 错误：错误）{ print("分享失败：\(错误)") } func itemTitle(for csc: UICloudSharingController) -> 字符串？ { 返回“我的共享列表” } } ### 管理参与者 // ✅ 检查参与者对于 share.participants 的参与者 { print("\(participant.userIdentity.nameComponents?.givenName ?? "未知")") print(" 接受: \(participant.acceptanceStatus)") print(" 权限：\(participant.permission)") // .readOnly, .readWrite, .none } // ✅ 删除参与者 share.removeParticipant(参与者) 尝试等待 privateDatabase.save(share) ### 接受分享 // 在 SceneDelegate 或 AppDelegate 中 func userDidAcceptCloudKitShareWith(_ cloudKitShareMetadata: CKShare.Metadata) { 让操作 = CKAcceptSharesOperation(shareMetadatas: [cloudKitShareMetadata]) operation.acceptSharesResultBlock = { 结果切换结果{ case .success: print("分享已接受") case .failure(let error): print("接受失败：\(error)") } } CKContainer（标识符：cloudKitShareMetadata.containerIdentifier） .add(操作) } ** ** ## 快速参考任务|现代 API（iOS 17+）|旧版 API ---|---|--- 结构化数据同步 | SwiftData + CloudKit | CKSyncEngine 或 CKDatabase 自定义持久同步 | CKSync引擎| CK数据库冲突解决 |自动（SwiftData/CKSyncEngine）|手动（保存策略）账户变更 |自动处理 |手动检测监控| CloudKit 控制台遥测 |手动记录 ** ** ## 相关技能 * `axiom-swiftdata` — SwiftData 实现细节 * `axiom-storage` — 选择 CloudKit 与 iCloud Drive * `axiom-icloud-drive-ref` — 基于文件的 iCloud 同步 * `axiom-cloud-sync-diag` — 调试 CloudKit 同步问题 ** ** **最后更新**：2025 年 12 月 12 日 **技能类型**：参考 **最低 iOS**：10.0（基本）、17.0（CKSyncEngine、SwiftData 集成） **WWDC 会议**：2023-10188（CKSyncEngine）、2024-10122（CloudKit 控制台）

Axiom Cloudkit 参考

包含技能