swift-actor-persistence

Swift Actors für Thread-sichere Persistenz

Muster für den Aufbau thread-sicherer Datenpersistenzschichten mit Swift-Actors. Kombiniert In-Memory-Caching mit dateibasierter Speicherung und nutzt das Actor-Modell, um Data Races zur Compile-Zeit zu eliminieren.

Wann aktivieren

• Aufbau einer Datenpersistenzschicht in Swift 5.5+
• Notwendigkeit eines thread-sicheren Zugriffs auf gemeinsam genutzte, veränderliche Zustände
• Wunsch, manuelle Synchronisation (Locks, DispatchQueues) zu vermeiden
• Entwicklung von Offline-First-Apps mit lokaler Speicherung

Kernmuster

Actor-basiertes Repository

Das Actor-Modell garantiert serialisierten Zugriff – keine Data Races, durch den Compiler erzwungen.

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)
        // Synchrones Laden während init (Actor-Isolation noch nicht aktiv)
        self.cache = Self.loadSynchronously(from: fileURL)
    }

    // MARK: - Öffentliche 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: - Privat

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

Verwendung

Aufgrund der Actor-Isolation sind alle Aufrufe automatisch async:

let repository = LocalRepository<Question>()

// Lesen – schnelle O(1)-Suche aus dem In-Memory-Cache
let question = await repository.find(by: "q-001")
let allQuestions = await repository.loadAll()

// Schreiben – aktualisiert den Cache und speichert atomar in die Datei
try await repository.save(newQuestion)
try await repository.delete("q-001")

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

Wichtige Designentscheidungen

Entscheidung	Begründung
Actor (nicht Klasse + Lock)	Compiler-erzwungene Thread-Sicherheit, keine manuelle Synchronisation
In-Memory-Cache + Dateipersistenz	Schnelle Lesevorgänge aus dem Cache, dauerhafte Schreibvorgänge auf die Festplatte
Synchrones Laden im Init	Vermeidung von asynchroner Initialisierungskomplexität
Dictionary, das nach ID indiziert ist	O(1)-Lookups nach Identifikator
Generisch über Codable & Identifiable	Wiederverwendbar für jeden Modelltyp
Atomare Dateischreibvorgänge (.atomic)	Verhindert partielle Schreibvorgänge bei Abstürzen

Bewährte Verfahren

• Verwenden Sie Sendable-Typen für alle Daten, die Actor-Grenzen überschreiten
• Halten Sie die öffentliche API des Actors minimal – exponieren Sie nur Domänenoperationen, keine Persistenzdetails
• Verwenden Sie .atomic-Schreibvorgänge, um Datenkorruption zu verhindern, falls die App während des Schreibens abstürzt
• Laden Sie synchron in init – asynchrone Initialisierer fügen Komplexität hinzu mit geringem Nutzen für lokale Dateien
• Kombinieren Sie mit @Observable ViewModels für reaktive UI-Updates

Anti-Patterns, die vermieden werden sollten

• Verwendung von DispatchQueue oder NSLock anstelle von Actors für neuen Swift-Concurrency-Code
• Exponieren des internen Cache-Dictionarys an externe Aufrufer
• Konfigurierbarmachen der Datei-URL ohne Validierung
• Vergessen, dass alle Actor-Methodenaufrufe await sind – Aufrufer müssen den asynchronen Kontext handhaben
• Verwendung von nonisolated, um die Actor-Isolation zu umgehen (macht den Zweck zunichte)

Wann verwenden

• Lokale Datenspeicherung in iOS/macOS-Apps (Benutzerdaten, Einstellungen, gecachte Inhalte)
• Offline-First-Architekturen, die später mit einem Server synchronisieren
• Jeglicher gemeinsam genutzter, veränderlicher Zustand, auf den mehrere Teile der App gleichzeitig zugreifen
• Ersetzen der Legacy-DispatchQueue-basierten Thread-Sicherheit durch moderne Swift-Concurrency