Swift Actor 持久化

使用 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)
        // 初始化期間同步載入（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 + lock）	編譯器強制執行執行緒安全，無需手動同步
記憶體快取 + 檔案持久化	從快取快速讀取，寫入磁碟持久可靠
同步初始化載入	避免非同步初始化的複雜性
以 ID 為鍵的字典	按識別碼 O(1) 查詢
泛型 Codable & Identifiable	可重複用於任何模型類型
原子性檔案寫入 (.atomic)	防止崩潰時的部分寫入

最佳實踐

• 使用 Sendable 類型 用於所有跨越 Actor 邊界的資料
• 保持 Actor 的公開 API 最小化 — 只暴露領域操作，不暴露持久化細節
• 使用 .atomic 寫入 以防止應用程式在寫入中途崩潰時資料損毀
• 在 init 中同步載入 — 非同步初始化器會增加複雜性，對本地檔案好處不大
• 搭配 @Observable ViewModel 以實現響應式 UI 更新

應避免的反模式

• 在新的 Swift 並行程式碼中使用 DispatchQueue 或 NSLock 取代 Actor
• 將內部快取字典暴露給外部呼叫者
• 讓檔案 URL 可設定但未經驗證
• 忘記所有 Actor 方法呼叫都需要 await — 呼叫者必須處理非同步上下文
• 使用 nonisolated 繞過 Actor 隔離（違背目的）

使用時機

• iOS/macOS 應用程式中的本地資料儲存（使用者資料、設定、快取內容）
• 離線優先架構，後續同步到伺服器
• 任何應用程式中多個部分同時存取的共享可變狀態
• 用現代 Swift 並行取代舊式基於 DispatchQueue 的執行緒安全