Swift Actor Persistence Skill 是 Everything Claude Code 插件体系下专为 Swift 设计的线程安全数据持久化能力。它通过 actor 模型自动实现并发安全，结合内存缓存与文件持久化，无需手动加锁或 DispatchQueue，彻底消除数据竞争。适用于 iOS/macOS 离线存储、并发访问等场景，是现代 Swift 并发架构的推荐实践。本文将详细讲解 Skill 的激活时机、完整用法、输出效果、与其他 Agent/Skill 的协作方式及常见注意事项。

Everything Claude Code Swift Actor Persistence Skill：用 Actor 消除数据竞争的线程安全 Swift 数据持久化

在 Swift 5.5 及以上版本，actor 模型为并发编程带来了革命性的线程安全保障。Everything Claude Code 的 swift-actor-persistence Skill，正是基于这一模型，提供了一套无需手动同步、零数据竞争的本地数据持久化方案。它将内存缓存与文件存储结合，适用于构建离线优先、并发访问频繁的 iOS/macOS 应用。

如果你正在使用 Claude Code、Codex 或 Cursor 等 AI 编程助手，并希望系统性提升 Swift 项目的并发安全与数据持久化质量，这一 Skill 能显著简化你的架构设计和代码实现。你也可以在Everything Claude Code 完全指南中了解 Skill/Agent/Hooks 体系的整体设计理念。

1. 这个 Skill 解决了什么问题？

在传统 Swift 持久化层设计中，开发者通常需要手动管理线程安全——比如用 DispatchQueue、NSLock 等手段保护共享状态。这不仅容易出错，还难以维护，稍有不慎就会引入数据竞争（data race）或死锁等并发 bug。

swift-actor-persistence Skill 采用 Swift actor 模型，编译器强制保证所有对持久化层的访问都是串行的，不可能出现数据竞争。Skill 内置内存缓存（O(1) 读取）与文件（JSON）持久化，兼顾性能与数据安全，且代码结构高度可复用、易于集成到任何 Swift 项目。

典型应用场景：

• iOS/macOS 本地数据存储（如用户数据、设置、缓存内容）
• 离线优先架构，后续可与服务器同步
• 多组件/多线程并发读写同一数据源

2. 何时激活（触发条件）

你可以在以下场景下主动启用该 Skill：

• 需要为 Swift 项目设计线程安全的数据持久化层
• 希望消除所有手动同步（不再写 lock/queue）
• 需要高性能本地缓存与持久化结合的方案
• 项目采用 Swift 5.5+ 并引入了现代并发（async/await、actor）

Skill 可通过 ECC 配置激活，也可由相关 Agent（如架构设计 Agent、代码生成 Agent）在分析到持久化需求时自动推荐。具体安装方法可参考安装配置指南。

3. Step by Step 使用流程

步骤 1：定义你的数据模型

要求模型实现 Codable 和 Identifiable（ID 类型为 String），例如：

struct Question: Codable, Identifiable {
    let id: String
    let text: String
}

步骤 2：创建 Actor 持久化仓库

Skill 提供了通用的 LocalRepository<T>：

public actor LocalRepository<T: Codable & Identifiable> where T.ID == String {
    // ...（见下方完整代码示例）
}

你可以直接实例化：

let repository = LocalRepository<Question>()

步骤 3：读写数据（全部自动 async）

所有操作都自动串行、线程安全，无需任何锁或队列：

// 读取（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")

步骤 4：结合 @Observable ViewModel 实现响应式 UI

Skill 推荐结合 SwiftUI 的 @Observable，实现数据驱动的 UI 更新：

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

步骤 5：持久化文件管理

Skill 默认将数据存储在 app 的 Documents 目录下的 data.json 文件。你可以通过构造参数自定义目录和文件名，但建议仅在经过严格校验后开放配置，避免路径注入或权限问题。

完整代码示例

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

4. 输出示例

预期效果：

• 并发读写时，所有数据操作自动串行，绝无数据竞争
• 读取速度极快（内存 O(1)），写入自动持久化且原子性保障
• ViewModel 层可直接 await repository，UI 响应式刷新
• 支持任意 Codable & Identifiable 模型，极易复用

示例输出：

let repo = LocalRepository<Question>()
try await repo.save(Question(id: "q-001", text: "什么是 Swift actor?"))
let q = await repo.find(by: "q-001") // -> Question(id: "q-001", text: "...")

await repo.loadAll() // -> [Question(id: "q-001", ...), ...]
try await repo.delete("q-001")

5. 常见配套 Agent 与 Skill 协作关系

• Architect Agent：在系统架构设计时自动推荐 Actor 持久化模式，替换传统锁/队列方案（详见Architect Agent）
• Code Reviewer Agent：审查并发安全与持久化实现，检测是否正确使用 actor，是否有绕过隔离的 anti-pattern
• SwiftUI Patterns Skill：结合 @Observable 与 actor repository，实现现代响应式 UI 与数据层解耦（详见SwiftUI Patterns Skill）
• Verification Loop Skill：在端到端测试中验证并发场景下的数据一致性和无竞争（详见Verification Loop）

6. 最佳实践与常见误区

最佳实践：

• 所有跨 actor 边界的数据类型使用 Sendable
• 只暴露必要的业务操作，不泄露内部 cache 结构
• 文件写入使用 .atomic，防止崩溃时数据损坏
• 初始化时同步加载，避免 async init 的复杂性
• 与 @Observable ViewModel 配合，提升 UI 响应性

常见误区（Anti-pattern）：

• 仍然手动用 DispatchQueue 或 NSLock 实现并发安全
• 直接暴露内部 cache，导致外部绕过 actor 隔离
• 忘记所有 actor 方法都需 await，错误地在同步上下文调用
• 滥用 nonisolated 破坏隔离性
• 文件路径配置不安全，可能引发安全漏洞

更多并发、持久化和验证的高级技巧，可参考Claude Code 高级技巧。

---

FAQ

Q: 这个 Skill 适合哪些类型的 Swift 项目？
A: 适合所有需要本地持久化且存在并发访问的数据场景，尤其是 iOS/macOS 离线优先、数据同步、缓存等业务。

Q: 如何与 SwiftUI 响应式架构结合？
A: 推荐将 Actor repository 注入 @Observable ViewModel，所有数据操作 await repository，UI 自动响应数据变更。

Q: Skill 能否替换现有的 DispatchQueue/NSLock 持久化实现？
A: 可以，且推荐迁移。Skill 的 actor 模型更安全、易维护，消除了手动同步的复杂性和隐患。

---