swift-actor-persistence

用途

该技能提供一套使用 Swift actor 构建线程安全数据持久化层的模式。它把内存缓存与文件后端存储结合起来，利用 actor 模型在编译期消除数据竞争，适合在 Swift 5.5+ 中构建本地持久化、离线优先或需要并发访问共享可变状态的应用。

主要能力

核心模式是「基于 actor 的仓库」。示例代码定义了一个泛型 actor：

public actor LocalRepository<T: Codable & Identifiable> where T.ID == String {
    private var cache: [String: T] = [:]
    private let fileURL: URL

    public init(directory: URL = .documentsDirectory, filename: String = "data.json") {
        self.fileURL = directory.appendingPathComponent(filename)
        // Synchronous load during init (actor isolation not yet active)
        self.cache = Self.loadSynchronously(from: fileURL)
    }

    // MARK: - Public API

    public func save(_ item: T) throws {
        cache[item.id] = item
        try persistToFile()
    }

    public func delete(_ id: String) throws {
        cache[id] = nil
        try persistToFile()
    }

    public func find(by id: String) -> T? {
        cache[id]
    }

    public func loadAll() -> [T] {
        Array(cache.values)
    }

    // MARK: - Private

    private func persistToFile() throws {
        let data = try JSONEncoder().encode(Array(cache.values))
        try data.write(to: fileURL, options: .atomic)
    }

    private static func loadSynchronously(from url: URL) -> [String: T] {
        guard let data = try? Data(contentsOf: url),
              let items = try? JSONDecoder().decode([T].self, from: data) else {
            return [:]
        }
        return Dictionary(uniqueKeysWithValues: items.map { ($0.id, $0) })
    }
}

该模式具备以下能力：

通过 actor 保证串行访问，由编译器强制线程安全，无需手动加锁。
内存缓存提供快速读取，文件持久化保证数据落盘。
以 ID 为键的字典实现 O(1) 查找。
泛型约束 Codable & Identifiable，可复用于任意模型类型。
使用 .atomic 原子写入，防止崩溃时产生部分写入。

使用方式

由于 actor 隔离，所有调用自动变为异步：

let repository = LocalRepository<Question>()

// Read — fast O(1) lookup from in-memory cache
let question = await repository.find(by: "q-001")
let allQuestions = await repository.loadAll()

// Write — updates cache and persists to file atomically
try await repository.save(newQuestion)
try await repository.delete("q-001")

可与 @Observable ViewModel 组合使用：

@Observable
final class QuestionListViewModel {
    private(set) var questions: [Question] = []
    private let repository: LocalRepository<Question>

    init(repository: LocalRepository<Question> = LocalRepository()) {
        self.repository = repository
    }

    func load() async {
        questions = await repository.loadAll()
    }

    func add(_ question: Question) async throws {
        try await repository.save(question)
        questions = await repository.loadAll()
    }
}

关键设计决策

使用 actor 而非 class + lock：由编译器强制线程安全，无需手动同步。
内存缓存 + 文件持久化：缓存提供快速读取，磁盘保证写入持久。
在 init 中同步加载：避免异步初始化的复杂度。
以 ID 为键的字典：按标识符实现 O(1) 查找。
泛型约束 Codable & Identifiable：可跨任意模型类型复用。
原子文件写入（.atomic）：防止崩溃时出现部分写入。

最佳实践

所有跨越 actor 边界的数据使用 Sendable 类型。
保持 actor 的公开 API 最小化，只暴露领域操作，不暴露持久化细节。
使用 .atomic 写入，防止应用在写入中途崩溃导致数据损坏。
在 init 中同步加载，异步初始化器对本地文件收益有限且增加复杂度。
与 @Observable ViewModel 组合，实现响应式 UI 更新。

应避免的反模式

在新的 Swift 并发代码中使用 DispatchQueue 或 NSLock 代替 actor。
将内部缓存字典暴露给外部调用者。
让文件 URL 可配置却不做校验。
忘记所有 actor 方法调用都是 await，调用方必须处理异步上下文。
使用 nonisolated 绕过 actor 隔离（违背初衷）。

适用场景

iOS/macOS 应用中的本地数据存储（用户数据、设置、缓存内容）。
离线优先、之后再与服务器同步的架构。
应用中多个部分并发访问的任何共享可变状态。
用现代 Swift 并发替换基于 DispatchQueue 的旧式线程安全方案。

限制

资料未提供该技能的具体安装命令、依赖要求、平台版本下限之外的兼容性说明、性能基准或收费信息，这些内容暂未提供。