swift-actor-persistence

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Swift Actors for Thread-Safe Persistence

利用Swift Actors实现线程安全的数据持久化

Patterns for building thread-safe data persistence layers using Swift actors. Combines in-memory caching with file-backed storage, leveraging the actor model to eliminate data races at compile time.

本文介绍如何使用Swift Actors构建线程安全的数据持久化层，结合内存缓存与文件存储，借助Actor模型在编译阶段就消除数据竞争问题。

When to Activate

适用场景

Building a data persistence layer in Swift 5.5+
Need thread-safe access to shared mutable state
Want to eliminate manual synchronization (locks, DispatchQueues)
Building offline-first apps with local storage

在Swift 5.5+版本中构建数据持久化层
需要对共享可变状态进行线程安全访问
希望摒弃手动同步方式（如锁、DispatchQueues）
开发支持离线优先的本地存储应用

Core Pattern

核心模式

Actor-Based Repository

基于Actor的仓库

The actor model guarantees serialized access — no data races, enforced by the compiler.

swift

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模型可保证序列化访问——编译器会强制确保无数据竞争。

swift

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)
        // 初始化时同步加载（此时Actor隔离尚未生效）
        self.cache = Self.loadSynchronously(from: fileURL)
    }

    // MARK: - 公开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 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) })
    }
}

Usage

使用示例

All calls are automatically async due to actor isolation:

swift

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")

由于Actor隔离机制，所有调用都会自动转为异步：

swift

let repository = LocalRepository<Question>()

// 读取操作——从内存缓存快速查找，时间复杂度O(1)
let question = await repository.find(by: "q-001")
let allQuestions = await repository.loadAll()

// 写入操作——更新缓存并以原子方式持久化到文件
try await repository.save(newQuestion)
try await repository.delete("q-001")

Combining with @Observable ViewModel

与@Observable ViewModel结合使用

swift

@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()
    }
}

swift

@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()
    }
}

Key Design Decisions

关键设计决策

Decision	Rationale
Actor (not class + lock)	Compiler-enforced thread safety, no manual synchronization
In-memory cache + file persistence	Fast reads from cache, durable writes to disk
Synchronous init loading	Avoids async initialization complexity
Dictionary keyed by ID	O(1) lookups by identifier
Generic over `Codable & Identifiable`	Reusable across any model type
Atomic file writes ( `.atomic` )	Prevents partial writes on crash

决策	理由
使用Actor而非“类+锁”	由编译器强制保证线程安全，无需手动同步
内存缓存+文件持久化	从缓存快速读取，写入操作持久化到磁盘保证数据耐用性
初始化时同步加载	避免异步初始化带来的复杂度
以ID为键的字典存储	通过标识符实现O(1)时间复杂度的查找
基于 `Codable & Identifiable` 泛型实现	可复用在任意模型类型上
原子文件写入（ `.atomic` ）	防止应用崩溃时出现部分写入的情况

Best Practices

最佳实践

Use
Sendable
types for all data crossing actor boundaries
Keep the actor's public API minimal — only expose domain operations, not persistence details
Use
.atomic
writes to prevent data corruption if the app crashes mid-write
Load synchronously in
init
— async initializers add complexity with minimal benefit for local files
Combine with
@Observable
ViewModels for reactive UI updates

所有跨Actor边界的数据都使用
Sendable
类型
精简Actor的公开API——仅暴露领域操作，而非持久化细节
使用
.atomic
写入方式——防止应用崩溃时数据损坏
在
init
中同步加载——异步初始化会增加复杂度，而本地文件加载的收益极小
与
@Observable
结合使用——实现响应式UI更新

Anti-Patterns to Avoid

需避免的反模式

Using
```
DispatchQueue
```
or
```
NSLock
```
instead of actors for new Swift concurrency code
Exposing the internal cache dictionary to external callers
Making the file URL configurable without validation
Forgetting that all actor method calls are
```
await
```
— callers must handle async context
Using
```
nonisolated
```
to bypass actor isolation (defeats the purpose)

在新的Swift并发代码中，使用
```
DispatchQueue
```
或
```
NSLock
```
替代Actors
向外部调用者暴露内部缓存字典
不对文件URL的可配置性做验证
忘记所有Actor方法调用都需要
```
await
```
——调用者必须处理异步上下文
使用
```
nonisolated
```
绕过Actor隔离机制（这会失去线程安全的意义）

When to Use

适用场景

Local data storage in iOS/macOS apps (user data, settings, cached content)
Offline-first architectures that sync to a server later
Any shared mutable state that multiple parts of the app access concurrently
Replacing legacy
```
DispatchQueue
```
-based thread safety with modern Swift concurrency

iOS/macOS应用中的本地数据存储（用户数据、设置、缓存内容）
后续需与服务器同步的离线优先架构
应用中多个部分需并发访问的共享可变状态
用现代Swift并发机制替代基于
```
DispatchQueue
```
的旧版线程安全实现