IceCream 帮助你将 Realm 数据库与 CloudKit 同步。

它像魔法一样工作！

• Realm 数据库

  • 离线优先
  • 线程安全
  • 响应式编程
  • 为移动应用优化
  • 易于迁移

• Apple CloudKit

  • 自动认证
  • 静默推送
  • 免费（有额度限制，私有数据库会占用你用户的 iCloud 存储空间）

• 增量更新

• 可达性（支持长时间运行的操作）

• 强大的错误处理

• 自动同步

• 支持多种对象模型

• 支持公共/私有数据库

• 大数据同步

• 也支持手动同步

• 支持关系（一对一/一对多）

• 可在所有 Apple 平台（iOS/macOS/tvOS/watchOS）上使用

• 支持 Realm 自然类型列表

• 完整的文档

1. 确保你已注册 Apple 开发者计划
2. 在 Capabilities 中启用 iCloud 并选择 CloudKit
3. 启用 Background Modes 并勾选 Background fetch 和 Remote notification

1. 准备好你的 Realm 对象（例如 Dog, Cat...）

class Dog: Object {
    @objc dynamic var id = NSUUID().uuidString
    @objc dynamic var name = ""
    @objc dynamic var age = 0
    @objc dynamic var isDeleted = false

    static let AVATAR_KEY = "avatar"
    @objc dynamic var avatar: CreamAsset?

    @objc dynamic var owner: Person? // to-one relationships must be optional

    override class func primaryKey() -> String? {
        return "id"
    }
}

2. 像这样操作

extension Dog: CKRecordConvertible & CKRecordRecoverable {
    // Leave it blank is all
}

就这么简单？ Protocol Extensions 实现了这个技巧。

3. 启动引擎！

var syncEngine: SyncEngine?
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    ...
    syncEngine = SyncEngine(objects: [
            SyncObject(type: Dog.self),
            SyncObject(type: Cat.self),
            SyncObject(type: Person.self)
        ])
    application.registerForRemoteNotifications()
    ...
}

4. 监听远程通知

AppDelegate 中的示例代码会是一个很好的参考。

这就是你需要做的全部！ 每次你写入 Realm， SyncEngine 都会收到通知并处理同步事务！

更多细节，请克隆项目查看源代码。

是的，我们强烈建议你使用软删除。 这就是为什么我们向 CKRecordConvertible 协议添加 isDeleted 属性的原因。

当你想要删除一个对象时，你只需要将其 isDeleted 属性设置为 true，其余的事情都已经处理好了。

你也不需要担心清理工作。 这也已经被考虑到了。

幸运的是，我们有一个完美的 asset 同步解决方案。 当然，你也可以将你的图像或资源之类的东西存储为 Data 类型，一切都运作良好。 但是 Realm 对数据属性有 16MB 的限制。 并且 CloudKit 鼓励我们在要分配给字段的数据大于几 KB 时使用 CKAsset。 因此，考虑到以上两点，我们建议你使用 CreamAsset 属性来保存数据。 CreamAsset 会将本地数据存储在文件系统上，并将文件路径保存在 Realm 中，一切都是自动的。 我们会将所有内容打包并上传到 CloudKit 作为 CKAsset。

提供了一个示例项目来查看详细的用法。

自 2.0 版本以来，IceCream 已经正式支持 Realm 关系（包括一对一和一对多）。

特别是对于支持一对多关系，你必须将 List 的元素类型传递给 SyncObject init 方法的参数。 例如

syncEngine = SyncEngine(objects: [
            SyncObject(type: Dog.self),
            SyncObject(type: Cat.self),
            SyncObject(type: Person.self, uListElementType: Cat.self) // if Person model has a List<Cat> property
        ])

• iOS 10.0+ / macOS 10.12+ / tvOS 10.0+ / watchOS 3.0+
• Swift 5

调试 CloudKit 确实很困难而且乏味。 但是当遇到难题时，我有一些技巧可以提供给你们。

• 你应该了解 Realm 和 CloudKit 的工作原理。
• 使用 GUI 工具，例如 Realm Browser 和 CloudKit Dashboard。
• 当你迷失并且不记得你在哪里时，我建议重新开始。 在 CloudKit Dashboard 中，提供了 “Reset...” 按钮。 你也可以通过重新安装应用来清除本地数据库。
• 默认情况下，IceCream 仅在 DEBUG 模式下将一些日志打印到你的控制台。 但是，如果它困扰了你，你可以通过添加 IceCream.shared.enableLogging = false 来关闭它。
• 保持冷静，继续前进！

警告：如果你要将你的应用发布到 App Store，请不要忘记将你的环境设置部署到生产环境。 你可以在 CloudKit Dashboard 中轻松地完成此操作。 还需要考虑读写权限。

如何在生产模式下调试 CloudKit？ 请参阅此 帖子。

要运行示例项目，请克隆该 repo，然后打开 Example/IceCream_Example.xcodeproj。

使用 Swift Package Manager、Carthage 或 CocoaPods。

从 Xcode 11 开始，你可以使用 Swift Package Manager 将 IceCream 及其依赖项添加到你的项目。

选择 File > Swift Packages > Add Package Dependency。 在 “Choose Package Repository” 对话框中输入 https://github.com/caiyue1993/IceCream.git。 在下一页中，将版本解析规则指定为 “Up to Next Major”，并将 “2.0.2” 作为其最早的版本。 在 Xcode 检出源代码并解析版本后，你可以选择 “IceCream” 库并将其添加到你的应用目标。

如果你在将软件包添加到 Xcode 项目时遇到任何问题或有疑问，我建议阅读 Apple 的 Adding Package Dependencies to Your App 指南文章。

Carthage 是 Cocoa 应用程序的去中心化依赖管理器。

要使用 Carthage 将 IceCream 集成到你的 Xcode 项目中，请在你的 Cartfile 中指定它

github "caiyue1993/IceCream"

然后，运行以下命令来构建 frameworks

carthage update

通常，你将获得 IceCream，Realm 和 RealmSwift frameworks。 你需要手动设置你的 Xcode 项目以添加这 3 个 frameworks。

在你的应用程序目标的 General 设置标签中，在 Linked Frameworks and Libraries 部分中，从磁盘上的 Carthage/Build 文件夹中拖放要使用的每个 framework。

在你的应用程序目标的 Build Phases 设置标签中，单击 “+” 图标并选择 “New Run Script Phase”。 创建一个包含以下内容的 Run Script

/usr/local/bin/carthage copy-frameworks

并在 “Input Files” 下添加要使用的 frameworks 的路径（以 iOS 平台为例）

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

有关如何使用 Carthage 的更多信息，请参阅其 项目页面。

IceCream 可通过 CocoaPods 获得。 要安装它，只需将以下行添加到你的 Podfile

pod 'IceCream'

如果你想将 IceCream 构建为静态 framework，则需要 CocoaPods 1.4.0+。

这是 IceCream 项目的待办事项列表。 你可以加入我们成为贡献者。

• CloudKit 共享数据库

有关贡献指南，请参阅 CONTRIBUTING 文件。

我的应用 Music Mate（Apple Music 的缺失伴侣）正在充分利用 IceCream。 你可以下载它并在你的多个设备上尝试它，看看这个魔法。

• 使用 CloudKit 同步数据（推荐）
• CloudKit 最佳实践
• 掌握 Realm 通知

这个项目之所以存在，要感谢所有贡献者

开源很棒，但需要时间和精力来维护。 如果你能以经济方式支持 IceCream 的维护，我将非常感激并受到激励。 你可以通过以下方式赞助该项目

• 成为我的 GitHub Sponsors，推荐
• 在 Open Collective 上支持我
• 通过 PayPal 直接转账捐款

并感谢我们在 open collective 上的所有支持者

IceCream 在 MIT 许可下可用。 有关更多信息，请参见 LICENSE 文件。