快速上手

相关源文件

本页面内容基于以下源文件生成：

• README.md
• Example/IceCream_Example/AppDelegate.swift
• Example/IceCream_Example/Dog.swift
• Example/IceCream_Example/Cat.swift
• Package.swift
• Cartfile
• IceCream/Classes/Manifest.swift
• IceCream/Classes/Syncable.swift
• IceCream/Classes/CreamAsset.swift
• IceCream/Classes/SyncEngine.swift

IceCream 是一个用于将 Realm Database 与 Apple CloudKit 进行同步的框架，支持离线优先、自动同步、关系映射等特性。以下内容将帮助开发者快速完成环境配置、安装集成与基础验证。

环境要求

在集成 IceCream 之前，需确认开发环境满足以下条件：

平台与版本要求：

• iOS 10.0+ / macOS 10.12+ / tvOS 10.0+ / watchOS 3.0+（Package.swift:6-8）
• Swift 5（Package.swift:27）

依赖项：

• Realm Cocoa：版本 4.1.1 及以上（Package.swift:15-18）
• CloudKit（系统框架，无需额外安装）

Apple 开发者配置：

1. 已加入 Apple Developer Program（README.md:46）
2. 在 Xcode Capabilities 中启用 iCloud，并选择 CloudKit（README.md:47）
3. 启用 Background Modes，勾选 Background fetch 和 Remote notification（README.md:48）

安装步骤

IceCream 支持三种主流的依赖管理工具：Swift Package Manager、Carthage 和 CocoaPods。

Swift Package Manager（推荐）

从 Xcode 11 开始，可直接通过 SPM 集成：

1. 在 Xcode 中选择 File > Swift Packages > Add Package Dependency
2. 输入仓库地址：https://github.com/caiyue1993/IceCream.git（README.md:170）
3. 版本规则选择 Up to Next Major，最低版本设为 2.0.2（README.md:171）
4. 解析完成后，将 IceCream 库添加到 App Target

Carthage

在项目根目录的 Cartfile 中添加：

ogdl
1github "caiyue1993/IceCream"

（Cartfile:1）

然后执行构建命令：

bash
1carthage update

（README.md:189）

构建完成后，需手动将 Carthage/Build 目录下的 IceCream.framework、Realm.framework 和 RealmSwift.framework 添加到 Xcode 项目的 Linked Frameworks and Libraries（README.md:192-194）。

同时在 Build Phases 中添加 Run Script：

bash
1/usr/local/bin/carthage copy-frameworks

（README.md:199）

并在 Input Files 中添加：

$(SRCROOT)/Carthage/Build/iOS/IceCream.framework
$(SRCROOT)/Carthage/Build/iOS/Realm.framework
$(SRCROOT)/Carthage/Build/iOS/RealmSwift.framework

（README.md:204-208）

CocoaPods

在 Podfile 中添加：

ruby
1pod 'IceCream'

（README.md:217）

然后执行 pod install。如需构建为静态框架，需要 CocoaPods 1.4.0+（README.md:220）。

安装方式对比

最短可运行路径

完成安装后，按以下步骤实现最小可运行配置：

步骤 1：定义 Realm 数据模型

创建一个继承自 Object 的类，并添加必要属性：

swift
1import RealmSwift
2import IceCream
3import CloudKit
4
5class Dog: Object {
6    @objc dynamic var id = NSUUID().uuidString
7    @objc dynamic var name = ""
8    @objc dynamic var age = 0
9    @objc dynamic var isDeleted = false
10    
11    override class func primaryKey() -> String? {
12        return "id"
13    }
14}

（Dog.swift:14-28）

关键点：

• 必须定义主键（通常为 id）
• 必须包含 isDeleted 属性用于软删除（README.md:110-112）

步骤 2：实现协议扩展

让模型遵循 CKRecordConvertible 和 CKRecordRecoverable 协议：

swift
1extension Dog: CKRecordConvertible & CKRecordRecoverable {
2    // 协议扩展会自动处理大部分逻辑，留空即可
3}

（Dog.swift:31-37）

步骤 3：初始化 SyncEngine

在 AppDelegate 中初始化同步引擎：

swift
1import IceCream
2import CloudKit
3import RealmSwift
4
5var syncEngine: SyncEngine?
6
7func application(_ application: UIApplication, 
8                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
9    
10    syncEngine = SyncEngine(objects: [
11        SyncObject(type: Dog.self),
12        SyncObject(type: Cat.self)
13    ])
14    
15    application.registerForRemoteNotifications()
16    return true
17}

（AppDelegate.swift:18-32）

步骤 4：处理远程通知

实现远程通知回调以触发同步：

swift
1func application(_ application: UIApplication, 
2                 didReceiveRemoteNotification userInfo: [AnyHashable : Any], 
3                 fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
4    
5    if let dict = userInfo as? [String: NSObject], 
6       let notification = CKNotification(fromRemoteNotificationDictionary: dict),
7       let subscriptionID = notification.subscriptionID,
8       IceCreamSubscription.allIDs.contains(subscriptionID) {
9        
10        NotificationCenter.default.post(
11            name: Notifications.cloudKitDataDidChangeRemotely.name, 
12            object: nil, 
13            userInfo: userInfo
14        )
15        completionHandler(.newData)
16    }
17}

（AppDelegate.swift:40-47）

运行验证

编译与运行

1. 克隆仓库并打开示例项目：

   bash
   1git clone https://github.com/caiyue1993/IceCream.git
   2cd IceCream
   3open Example/IceCream_Example.xcodeproj

   （README.md:160）

2. 在 Xcode 中选择目标设备或模拟器，点击运行

验证同步功能

本地数据库验证：

• 使用 Realm Browser 查看本地 Realm 文件
• 确认数据模型已正确创建并包含 id、isDeleted 等字段

CloudKit 验证：

• 登录 CloudKit Dashboard
• 选择对应的 Container 和 Zone
• 确认记录已同步到 CloudKit（README.md:147）

日志输出验证：

• 在 DEBUG 模式下，IceCream 会自动输出同步日志（Manifest.swift:25-34）
• 如需关闭日志，可设置：

  swift
  1IceCream.shared.enableLogging = false

  （Manifest.swift:19）

常见问题与排错

问题 1：CloudKit 同步失败

症状：数据未同步到 CloudKit，控制台无错误输出

排查步骤：

1. 确认已在 Apple Developer Program 中启用 iCloud（README.md:46）
2. 检查 Xcode Capabilities 中 iCloud 是否已启用并选择 CloudKit
3. 在 CloudKit Dashboard 中确认 Schema 已创建
4. 如需重置环境，可在 CloudKit Dashboard 中点击 "Reset..." 按钮（README.md:148）

问题 2：远程通知未触发同步

症状：应用在后台时无法接收数据更新

排查步骤：

1. 确认 Background Modes 中已勾选 Remote notification（README.md:48）
2. 检查 didReceiveRemoteNotification 回调是否正确实现（AppDelegate.swift:40-47）
3. 确认 application.registerForRemoteNotifications() 已在启动时调用（AppDelegate.swift:32）

问题 3：关系同步异常

症状：To-One 或 To-Many 关系未正确同步

解决方案：

• To-One 关系必须声明为可选类型（Dog.swift:24）
• To-Many 关系需在 SyncObject 初始化时指定元素类型：

  swift
  1SyncObject(type: Person.self, uListElementType: Cat.self)

  （AppDelegate.swift:25）

问题 4：大数据同步性能问题

症状：同步大量数据时应用卡顿

解决方案：

• 对于超过几 KB 的数据，使用 CreamAsset 替代 Data 类型（CreamAsset.swift:13-19）
• CreamAsset 会将数据存储在文件系统，仅在 Realm 中保存路径，避免 16MB 限制

问题 5：生产环境部署

症状：开发环境正常，生产环境同步失败

解决方案：

• 在 CloudKit Dashboard 中将 Schema 部署到生产环境（README.md:152）
• 检查读写权限配置
• 参考 Stack Overflow 讨论 了解如何在开发阶段测试生产环境（README.md:156）

下一步建议

完成快速上手后，建议进一步了解以下内容：

1. 资产同步：学习如何使用 CreamAsset 处理图片等大型资源文件（CreamAsset.swift:20-39）

2. 软删除机制：深入理解 isDeleted 属性的工作原理与数据清理策略（README.md:108-114）

3. 公共数据库同步：了解如何配置 databaseScope: .public 实现公共数据共享（AppDelegate.swift:28-30）

4. Syncable 协议：研究底层同步接口以实现自定义同步逻辑（Syncable.swift:14-37）

5. 错误处理：探索 SyncEngine 的错误处理机制与重试策略

建议直接查看示例项目源码以获取更完整的实现参考（README.md:106）。