CloudKitSyncMonitor

CloudKitSyncMonitor 是一个 Swift 包，它监听 NSPersistentCloudKitContainer 发送的通知，并将这些通知转换为已发布的属性，从而为你的应用程序提供实时的同步状态信息。

此包解决了 CloudKit（以及因此你的应用程序）可能在没有警告或用户通知的情况下停止同步的关键问题。CloudKitSyncMonitor 提供对此类情况的即时检测，使你能够立即通知用户并采取适当的措施。

功能和行为 🌟

核心功能 🛠️

📡 通过拦截和解释 NSPersistentCloudKitContainer 通知来监视同步状态
🧠 通过同时考虑网络可用性和 iCloud 帐户状态来智能评估同步健康状况
🔍 公开一个 SyncMonitor 类，可以通过 SyncMonitor.default 单例方便地访问

通知订阅 📬

SyncMonitor 主动订阅来自关键系统组件的通知

🔄 NSPersistentCloudKitContainer: 用于核心同步事件监视
☁️ CKContainer: 用于跟踪 CloudKit 特定的状态
🌐 NWPathMonitor: 用于网络状态更新

重要提示 ⚠️为了确保准确和及时的状态信息，请在应用程序生命周期中尽早调用 SyncMonitor.default.startMonitoring()，最好是在你的应用程序委托或初始视图中。

信息级别 📊

SyncMonitor 在两个不同的粒度级别提供同步信息

顶层

syncStateSummary 属性提供了一个高级枚举，总结了整体同步状态。这非常适合快速状态检查和面向用户的信息。

详细级别

SyncMonitor 跟踪 NSPersistentCloudKitContainer 的三种主要事件类型的状态

Setup (设置): 同步环境的初始化
Import (导入): 从 CloudKit 到本地存储的传入数据
Export (导出): 从本地存储到 CloudKit 的传出数据

为了监视这些事件，SyncMonitor 提供了相应的属性

setupState: 跟踪设置事件的状态
importState: 监视导入事件的状态
exportState: 跟踪导出事件的状态

这些属性提供了关于每个同步阶段的全面信息，包括用于提取常用详细信息的便捷方法。

问题检测 🚨

SyncMonitor 提供了强大的工具来识别同步问题

一般检测

🔴 hasSyncError: 一个布尔值，指示是否存在任何与同步相关的错误
🟡 isNotSyncing: 检测到同步应该正常运行但没有按预期运行的情况

特定错误信息

setupError: 捕获同步设置阶段的问题
importError: 识别从 CloudKit 导入数据的问题
exportError: 突出显示导出数据到 CloudKit 时的问题

特殊属性 🔑

isNotSyncing 属性对于检测微妙的同步问题特别有用

它指示设置已成功完成，但没有导入事件开始，并且没有报告任何错误
这可以揭示边缘情况，例如操作系统级别的密码重新输入提示，其中 CloudKit 认为该帐户“可用”，但 NSPersistentCloudKitContainer 无法启动同步
与其他属性一样，它会将网络可用性和 iCloud 帐户状态考虑在内，以进行准确的报告

错误检测的重要性⚠️

及时准确的错误检测对于维护数据完整性和用户信任至关重要

🛡️ 通过在同步失败导致冲突或数据分歧之前识别它们来防止潜在的数据丢失
⚡ 能够立即检测和报告同步异常，通常在用户注意到任何问题之前
😊 通过提供透明、实时的同步状态信息，显着增强用户体验
🏆 有助于维护应用程序在不同设备上的可靠性和数据一致性

详细同步信息 📋

setupState, importState, 和 exportState 属性提供了对同步过程的全面见解

每个事件类型的当前状态 (未启动、进行中、已成功或失败)
每个同步事件的精确开始和结束时间
适用时提供详细的错误信息

显示详细同步状态的用法示例

fileprivate var dateFormatter: DateFormatter = {
    let dateFormatter = DateFormatter()
    dateFormatter.dateStyle = .short
    dateFormatter.timeStyle = .short
    return dateFormatter
}()

print("Setup state: \(stateText(for: SyncMonitor.default.setupState))")
print("Import state: \(stateText(for: SyncMonitor.default.importState))")
print("Export state: \(stateText(for: SyncMonitor.default.exportState))")

func stateText(for state: SyncMonitor.SyncState) -> String {
    switch state {
    case .notStarted:
        return "Not started"
    case .inProgress(started: let date):
        return "In progress since \(dateFormatter.string(from: date))"
    case let .succeeded(started: _, ended: endDate):
        return "Succeeded at \(dateFormatter.string(from: endDate))"
    case let .failed(started: _, ended: endDate, error: _):
        return "Failed at \(dateFormatter.string(from: endDate))"
    }
}

有关所有可用属性和方法的更多详细信息，请参阅全面的 SyncMonitor 文档。

用法示例 🚀

处理错误

private let syncMonitor = SyncMonitor.default

if syncMonitor.hasSyncError {
    if let error = syncMonitor.setupError {
        print("Unable to set up iCloud sync, changes won't be saved! \(error.localizedDescription)")
    }
    if let error = syncMonitor.importError {
        print("Import is broken: \(error.localizedDescription)")
    }
    if let error = syncMonitor.exportError {
        print("Export is broken - your changes aren't being saved! \(error.localizedDescription)")
    }
} else if syncMonitor.isNotSyncing {
    print("Sync should be working, but isn't. Look for a badge on Settings or other possible issues.")
}

显示错误状态

import SwiftUI
import CloudKitSyncMonitor

struct SyncStatusView: View {
    
    @StateObject private var syncMonitor = SyncMonitor.default

    var body: some View {
         if syncMonitor.syncStateSummary.isBroken {
             Image(systemName: syncMonitor.syncStateSummary.symbolName)
                 .foregroundColor(syncMonitor.syncStateSummary.symbolColor)
         }
    }
}

显示当前同步状态

import SwiftUI
import CloudKitSyncMonitor

struct SyncStatusView: View {
    
    @StateObject private var syncMonitor = SyncMonitor.default

    var body: some View {
        Image(systemName: syncMonitor.syncStateSummary.symbolName)
            .foregroundColor(syncMonitor.syncStateSummary.symbolColor)
    }
}

条件显示

if syncMonitor.syncStateSummary.isBroken || syncMonitor.syncStateSummary.isInProgress {
    Image(systemName: syncMonitor.syncStateSummary.symbolName)
        .foregroundColor(syncMonitor.syncStateSummary.symbolColor)
}

检查特定状态

if case .accountNotAvailable = syncMonitor.syncStateSummary {
    Text("Hey, log into your iCloud account if you want to sync")
}

安装 📦

Swift Package Manager (Swift 包管理器)

将以下内容添加到你的 Package.swift

dependencies: [
    .package(url: "https://github.com/ggruen/CloudKitSyncMonitor.git", from: "3.0.0"),
],
targets: [
    .target(
        name: "MyApp", // Where "MyApp" is the name of your app
        dependencies: ["CloudKitSyncMonitor"]),
]

Xcode

选择 File (文件) » Swift Packages (Swift 包) » Add Package Dependency... (添加包依赖项...)
输入仓库 URL: https://github.com/ggruen/CloudKitSyncMonitor.git
选择 "Up to next major version" (直到下一个主要版本)，并将 3.0.0 作为最低版本。

开发 🛠️

🍴 Fork 仓库
📥 在你的开发系统上 Check out
📁 将包含此 README 的文件夹 (CloudKitSyncMonitor) 拖到你的 Xcode 项目或工作区中。这将使 Xcode 选择本地版本，而不是包管理器中的版本。
🔧 如果你还没有通过 File (文件) > Swift Packages (Swift 包) 添加它，请进入你的项目 > General (通用) 选项卡 > Frameworks, Libraries and Embedded Content (框架、库和嵌入的内容)，然后单击 + 按钮添加它。你可能需要退出并重新启动 Xcode，才能使新包出现在列表中，以便你可以选择它。
🖊️ 进行更改，提交并推送到 Github
🚀 提交 pull request

要返回使用 github 版本，只需从侧边栏中删除 CloudKitSyncMonitor（单击它，按删除键，选择删除引用）- Xcode 应回退到你使用上面的安装说明添加的版本。如果你尚未将其安装为包依赖项，则只需从侧边栏中删除它，然后使用上面的安装说明将其添加为包依赖项。

如果你发现错误、有建议或问题等，也可以提交 issues。 🐛💡❓