Agent Skills › cavaldos/Lumio › swift-actor-persistence

swift-actor-persistence

GitHub

基于Swift Actor模型构建线程安全的数据持久化层,结合内存缓存与文件存储,通过编译器强制消除数据竞争,适用于离线优先应用。

.agents/skills/swift-actor-persistence/SKILL.md cavaldos/Lumio

触发场景

在Swift中构建线程安全的数据持久化层 需要对共享可变状态进行线程安全访问 希望消除手动同步(锁、DispatchQueue)

安装

npx skills add cavaldos/Lumio --skill swift-actor-persistence -g -y
更多选项

非标准路径

npx skills add https://github.com/cavaldos/Lumio/tree/main/.agents/skills/swift-actor-persistence -g -y

不安装直接使用

npx skills use cavaldos/Lumio@swift-actor-persistence

指定 Agent (Claude Code)

npx skills add cavaldos/Lumio --skill swift-actor-persistence -a claude-code -g -y

安装 repo 全部 skill

npx skills add cavaldos/Lumio --all -g -y

预览 repo 内 skill

npx skills add cavaldos/Lumio --list

SKILL.md

Frontmatter
{
    "name": "swift-actor-persistence",
    "origin": "ECC",
    "description": "在 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)
        // 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 隔离,所有调用都会自动变为异步:

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

与 @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(而非类 + 锁) 编译器强制执行的线程安全性,无需手动同步
内存缓存 + 文件持久化 从缓存中快速读取,持久化写入磁盘
同步初始化加载 避免异步初始化的复杂性
按 ID 键控的字典 按标识符进行 O(1) 查找
泛型化 Codable & Identifiable 可在任何模型类型中重复使用
原子文件写入 (.atomic) 防止崩溃时部分写入

最佳实践

  • 对所有跨越 actor 边界的数据使用 Sendable 类型
  • 保持 actor 的公共 API 最小化 —— 仅暴露领域操作,而非持久化细节
  • 使用 .atomic 写入 以防止应用在写入过程中崩溃导致数据损坏
  • 在 init 中同步加载 —— 异步初始化器会增加复杂性,而对本地文件的益处微乎其微
  • 与 @Observable ViewModel 结合使用 以实现响应式 UI 更新

应避免的反模式

  • 在 Swift 并发新代码中使用 DispatchQueue 或 NSLock 而非 actor
  • 将内部缓存字典暴露给外部调用者
  • 在不进行验证的情况下使文件 URL 可配置
  • 忘记所有 actor 方法调用都是 await —— 调用者必须处理异步上下文
  • 使用 nonisolated 来绕过 actor 隔离(违背了初衷)

何时使用

  • iOS/macOS 应用中的本地数据存储(用户数据、设置、缓存内容)
  • 稍后同步到服务器的离线优先架构
  • 应用中多个部分并发访问的任何共享可变状态
  • 用现代 Swift 并发性替换基于 DispatchQueue 的旧式线程安全机制

版本历史

  • ea79ca0 当前 2026-11-19 02:51

同 Skill 集合

.agents/skills/liquid-glass-design/SKILL.md
.agents/skills/swiftui-pro/SKILL.md
.agents/skills/swiftui-pro/skills/swiftui-pro/SKILL.md

元信息

文件数
0
版本
ea79ca0
Hash
41cbee87
收录时间
2026-11-19 02:51

首页 - Wiki
Copyright © 2011-2026 iteam. Current version is 2.156.0. UTC+08:00, 2026-11-19 03:18
浙ICP备14020137号-1