swift-actor-persistence

스레드 안전한 영속화를 위한 Swift Actors (Swift Actors for Thread-Safe Persistence)

Swift actor를 이용해 스레드 안전한 데이터 영속화 레이어를 만드는 패턴입니다. 메모리 캐시와 파일 기반 저장을 결합하고, actor 모델을 활용해 컴파일 단계에서 데이터 레이스를 없앱니다.

활성화 시점

• Swift 5.5+에서 데이터 영속화 레이어를 만들 때
• 공유 가변 상태에 대한 스레드 안전 접근이 필요할 때
• 수동 동기화(lock, DispatchQueue)를 제거하고 싶을 때
• 로컬 저장소를 쓰는 offline-first 앱을 만들 때

핵심 패턴

Actor 기반 레포지토리 (Actor-Based Repository)

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)
        self.cache = Self.loadSynchronously(from: fileURL)
    }

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

    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 격리 때문에 모든 호출은 자동으로 async가 됩니다.

let repository = LocalRepository<Question>()

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 사용	컴파일러가 강제하는 스레드 안전성
메모리 캐시 + 파일 저장	빠른 읽기 + 디스크 내구성
동기 init 로딩	async init의 복잡성 회피
ID 키 딕셔너리	O(1) 조회 성능
Codable & Identifiable 제네릭	여러 모델에 대한 재사용 가능성
.atomic 파일 쓰기	앱 중단 시 부분 쓰기(partial write) 방지

모범 사례

• actor 경계를 넘는 데이터는 Sendable 타입을 사용합니다.
• actor의 public API는 최소화합니다.
• 데이터 손상을 막기 위해 .atomic 쓰기를 사용합니다.
• 로컬 파일이면 init에서 동기 로딩을 선호합니다.
• 반응형 UI 업데이트에는 @Observable ViewModel과 결합합니다.

피해야 할 안티패턴

• 현대적인 Swift concurrency 코드에서 actors 대신 DispatchQueue나 NSLock 사용
• 내부 캐시 딕셔너리를 외부에 노출
• 검증 없이 파일 URL 구성 가능하게 만들기
• 모든 actor 메서드 호출 시 await가 필요하다는 점을 잊는 것
• nonisolated로 actor 격리를 우회하는 것

적합한 사용 사례

• iOS/macOS 앱의 로컬 데이터 저장
• 나중에 서버와 동기화하는 offline-first 아키텍처
• 앱의 여러 부분에서 동시에 접근하는 공유 가변 상태
• 기존 DispatchQueue 기반의 스레드 안전 코드를 현대적인 Swift concurrency로 교체할 때