使用 Swift Actor 實現執行緒安全的持久化
使用 Swift Actor 建立執行緒安全資料持久化層的模式。結合記憶體快取與檔案備份儲存，利用 Actor 模型在編譯時消除資料競爭。
啟動時機
- 在 Swift 5.5+ 中建立資料持久化層
- 需要對共用可變狀態進行執行緒安全存取
- 希望消除手動同步機制（鎖、DispatchQueues）
- 建構離線優先的應用程式，具備本地儲存
核心模式
基於 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)
// 在 init 中同步載入（此時 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) })
}
}
使用方式
由於 Actor 隔離，所有呼叫都會自動變成非同步：
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")
結合 @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 + 鎖） | 編譯器強制執行執行緒安全，無需手動同步 |
| 記憶體快取 + 檔案持久化 | 從快取快速讀取，寫入磁碟持久耐用 |
| 同步 init 載入 | 避免非同步初始化的複雜度 |
| 以 ID 為鍵的字典 | 根據識別碼進行 O(1) 查詢 |
泛型於 Codable & Identifiable | 可重複用於任何模型類型 |
原子性檔案寫入 (.atomic) | 防止崩潰時的部分寫入 |
最佳實踐
- 使用
Sendable類型 處理所有跨 Actor 邊界的資料 - 保持 Actor 的公開 API 最小化——只暴露領域操作，而非持久化細節
- 使用
.atomic寫入 防止應用程式在寫入中途崩潰時導致資料損毀 - 在
init中同步載入——非同步初始化增加複雜度，但對於本地檔案回報有限 - 結合
@ObservableViewModel 實現反應式 UI 更新
應避免的反模式
- 在全新的 Swift 並行程式碼中使用
DispatchQueue或NSLock替代 Actor - 將內部快取字典暴露給外部呼叫者
- 在未經驗證的情況下讓檔案 URL 可配置
- 忘記所有 Actor 方法呼叫都需
await——呼叫者必須處理非同步上下文 - 使用
nonisolated繞過 Actor 隔離（違背其目的）
使用時機
- iOS/macOS 應用中的本地資料儲存（使用者資料、設定、快取內容）
- 離線優先架構，稍後再同步到伺服器
- 任何應用程式中多個部分並發存取的共用可變狀態
- 用現代 Swift 並行程式取代傳統基於
DispatchQueue的執行緒安全機制