---

name: swift-actor-persistence description: 使用 Swift Actor 实现线程安全的数据持久化——内存缓存配合文件存储，从设计上消除数据竞争。 origin: ECC

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

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 + 锁） | 编译器强制的线程安全，无需手动同步 | | 内存缓存 + 文件持久化 | 从缓存快速读取，持久写入磁盘 | | 同步初始化加载 | 避免异步初始化复杂性 | | 以 ID 为键的字典 | O(1) 标识符查找 | | 泛型设计 | 可复用于任何 Codable & Identifiable 类型 |

何时选择 Actor vs 其他方案

| 方案 | 适用场景 | |------|----------| | Actor | 需要序列化访问共享可变状态 | | Sendable struct | 不可变值类型，无共享状态 | | @MainActor | UI 绑定状态，始终在主线程 | | AsyncStream | 事件流，观察者模式 |

常见陷阱

• 不要在 Actor 内部调用同步阻塞操作（如大文件 I/O）
• 避免 Actor 之间的循环依赖
• 初始化时的文件加载是同步的——保持数据量合理
• 使用 .atomic 写入选项防止文件损坏