用于线程安全持久化的 Swift Actor¶

使用 Swift actor 构建线程安全数据持久化层的模式。结合内存缓存和文件后端存储，利用 actor 模型在编译时排除数据竞争。

启动条件¶

当使用 Swift 5.5 或更高版本构建数据持久化层时
当需要对共享可变状态进行线程安全访问时
当希望消除手动同步（锁、DispatchQueue）时
当构建具有本地存储的离线优先应用时

核心模式¶

基于 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 {
        let previous = cache[item.id]
        cache[item.id] = item
        do {
            try persistToFile()
        } catch {
            // ディスク書き込み失敗時はキャッシュをロールバックして整合性を維持
            cache[item.id] = previous
            throw error
        }
    }

    public func delete(_ id: String) throws {
        let previous = cache[id]
        cache[id] = nil
        do {
            try persistToFile()
        } catch {
            // ディスク書き込み失敗時はキャッシュをロールバックして整合性を維持
            cache[id] = previous
            throw error
        }
    }

    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 隔离，所有调用都自动变为异步：

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（而不是类 + 锁）	由编译器强制的线程安全性，无需手动同步
内存缓存 + 文件持久化	从缓存快速读取，向磁盘持久化写入
初始化时同步加载	避免异步初始化的复杂性
以 ID 为键的字典	通过标识符进行 O(1) 查找
泛型 `Codable & Identifiable`	可复用于任何模型类型
原子文件写入（`.atomic`）	防止崩溃时部分写入

最佳实践¶

对所有跨越 Actor 边界的数据使用 Sendable 类型
最小化 Actor 的公开能力 —— 只公开领域操作，而不是持久化细节
使用 .atomic 写入 —— 防止写入过程中应用崩溃导致数据损坏
在 init 中同步加载 —— 异步初始化器会增加复杂性，而相对于本地文件只有微小优势
与 @Observable ViewModel 组合 —— 实现响应式 UI 更新

应避免的反模式¶

在 Swift 新并发代码中使用 DispatchQueue 或 NSLock 代替 Actor
将内部缓存字典暴露给外部调用方
允许在初始化后从外部修改文件 URL（只允许在初始化时设置）
忘记所有 Actor 方法调用都需要 await —— 调用方需要处理异步上下文
使用 nonisolated 绕过 Actor 隔离（本末倒置）

使用场景¶

iOS/macOS 应用的本地数据存储（用户数据、设置、缓存内容）
稍后与服务器同步的离线优先架构
被应用多个部分并发访问的共享可变状态
将基于 DispatchQueue 的遗留线程安全机制替换为最新的 Swift 并发

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 ev/ECC