AI 开发

2026 Swift 6.2 SwiftData:并发数据层怎么分步改造?

2026 Swift 6.2 SwiftData:并发数据层怎么分步改造?

编译器突然报出一串 @Sendable、Actor 隔离和 ModelContext 访问错误,最容易出现的误操作是给整个项目添加 @MainActor,结果编译通过了,列表滚动、批量导入和窗口切换却开始卡顿。

获胜者是“先固定工具链,再改一条写入链路”的分阶段方案。 对仍锁定 Swift 6.2 的项目,应先保存复现基线,再把一个高风险写入路径收口到 @ModelActor,跨 Actor 只传 PersistentIdentifier、不可变值类型或明确符合 Sendable 的 DTO。不要用 @unchecked Sendable、@preconcurrency 或同步等待批量消警。

这篇文章适合仍需维护 Swift 6.2 分支、不能一次重写持久化层的开发者,也适合负责拆分 SwiftData 数据访问边界的架构师和技术负责人。需要在独立 Mac 环境中并行验证旧分支与新分支的人,也可以按本文的回滚点执行。

动手前:先纠正版本线,再保存失败样本

先纠正一个容易影响排查方向的前提:Swift 6.2 对应的是 Xcode 26 初始版本线,而不是 Xcode 18。官方版本说明显示,Xcode 26 初始版本包含 Swift 6.2;Xcode 26.6 已包含 Swift 6.3。因此,本文讨论的是仍锁定 Swift 6.2 的维护分支,不把它描述成当前最新版。(developer.apple.com)

同时,Swift 6 语言模式和默认 Actor 隔离是按 target、模块或文件配置的,并不是所有老项目都会被工具链自动切换到同一种严格模式。Swift 6.2 还引入了按模块控制默认 Actor 隔离的能力,配置为 MainActor 会改变未显式标注代码的推断结果。(github.com)

第一小时不要急着改业务代码。先记录以下内容:

  • 每个 App、Framework 和 Swift Package target 的 Swift 语言模式。
  • 并发检查等级、默认 Actor 隔离和是否启用了 upcoming feature。
  • 当前 Xcode、SDK、Swift 编译器和依赖版本。
  • 可以重复触发问题的最小测试、输入数据、日志和旧分支。
  • 一次连续写入、一次取消任务、一次前后台切换的原始结果。

失败改造案例通常是这样的:开发者把 @MainActor 加到 Repository、Model、Service 和导入任务上,编译器诊断明显减少,但批量导入与界面共用主 Actor,原本应该后台执行的读取、转换和保存被挤进同一条执行路径。此时“卡顿”只能说明活性变差,不能直接命名为 SwiftData 内部死锁。

完成证据是:同一输入可以在旧分支重复触发;旧分支保存了诊断和线程采样;新分支每次改动都能与旧结果对照。若无法复现,先不要扩大迁移范围。

首条链路:从所有权图中挑出高风险写入

不要从报错数量最多的文件开始。应从一条最常出问题的新增、更新或批量导入链路开始,通常是“后台任务接收数据 → 创建模型 → 保存 → UI 刷新”。

沿着这条链路只画四类节点:

  1. ModelContainer 由谁创建,生命周期是否覆盖整个任务。
  2. ModelContext 由谁持有,是否是 SwiftUI 环境中绑定主 Actor 的上下文。
  3. @Model 实例在哪个隔离域内创建、修改和保存。
  4. UI 状态、后台任务和取消处理分别由谁持有。

官方文档明确说明,SwiftData 的 ModelContext 负责模型生命周期、插入、删除和保存;SwiftUI 环境提供的上下文绑定主 Actor,Query 也使用该上下文。后台上下文不能因为“看起来只是一个引用”就直接交给界面层。(developer.apple.com)

这里要把四种现象分开:

  • 编译诊断:类型或闭包不满足 Sendable,或跨 Actor 访问没有 await。
  • 运行时隔离失败:对象在错误的隔离域中访问,出现断言、崩溃或不一致行为。
  • 主线程阻塞:工作没有死锁,但大量查询、转换或保存占用了主 Actor。
  • 真实循环等待:必须有线程采样、任务回溯或调用栈证明存在互相等待。

调用栈显示任务正在等待数据库 I/O,不等于数据库死锁;界面停止响应,也不等于 @ModelActor 内部发生锁竞争。ModelActor 提供的是对模型属性的互斥访问能力,以及由其 modelContext 串行化该 Actor 中执行代码的机制,不能据此解释所有假死现象。(developer.apple.com)

首个提交:用单一职责的 @ModelActor 收口写入

首个提交只做一件事:让一条写入链路在自己的模型 Actor 内闭合完成。查询、修改和保存都在这个 Actor 的 ModelContext 中执行,调用方不传入另一个上下文管理的模型实例。

一个可控的最小边界可以这样写:

import SwiftData

@ModelActor
actor ImportStore {
    func insertRecord(
        title: String,
        sourceID: String
    ) throws -> PersistentIdentifier {
        let record = Record(title: title, sourceID: sourceID)
        modelContext.insert(record)
        try modelContext.save()
        return record.persistentModelID
    }
}

调用方只传递执行所需的值:

let store = ImportStore(modelContainer: container)

let id = try await store.insertRecord(
    title: input.title,
    sourceID: input.sourceID
)

这个模板不是适配所有架构的万能方案。它表达的只是三个边界:

  • ImportStore 自己拥有写入上下文。
  • 调用方不把 Record 实例从主 Actor 送进后台。
  • 返回值不是模型对象,而是可跨隔离传递的身份。

官方 ModelActor 接口包含 modelContainer、modelContext 和模型访问下标,并继承 Actor 与 Sendable;它的作用是为符合协议的模型 Actor 提供互斥模型访问,不是自动修复业务层的循环等待。(developer.apple.com)

如果项目使用依赖注入,可以把 ImportStore 作为具体实现注入到导入用例中,而不是把 ModelContext 注入所有 Service:

struct ImportUseCase {
    let store: ImportStore

    func run(_ input: ImportInput) async throws -> PersistentIdentifier {
        try await store.insertRecord(
            title: input.title,
            sourceID: input.sourceID
        )
    }
}

完成证据是:该提交只影响一条写入路径;原有 UI 查询仍可工作;取消、保存失败和重复导入都有测试结果;旧实现仍能通过开关调用。

当天接入:模型对象换成可发送的数据契约

@ModelActor 返回模型对象还是可发送的数据?

跨 Actor 返回 @Model 对象通常会把上下文所有权问题重新带回来。更稳妥的选择是返回三类数据:

  • PersistentIdentifier:接收方只需要知道哪个对象发生变化。
  • 不可变值类型:例如 struct ImportResult: Sendable。
  • 明确声明符合 Sendable 的展示 DTO:只包含 UI 需要的字段。

PersistentIdentifier 是 SwiftData 模型的聚合身份类型,官方定义中它符合 Sendable、Hashable、Codable 和 Identifiable。因此,它适合在 Actor 边界传递,但接收方仍应在自己的上下文中重新获取模型,不能把一个上下文中的模型引用当成全局对象使用。(developer.apple.com)

struct RecordRow: Sendable, Identifiable {
    let id: PersistentIdentifier
    let title: String
    let sourceID: String
}

@ModelActor
actor RecordReader {
    func row(for id: PersistentIdentifier) throws -> RecordRow? {
        guard let record = modelContext.registeredModel(
            for: id
        ) as Record? else {
            return nil
        }

        return RecordRow(
            id: record.persistentModelID,
            title: record.title,
            sourceID: record.sourceID
        )
    }
}

后台写入避免把模型传回主 Actor,关键不是加更多 await,而是把契约改成值。写入 Actor 返回保存结果、身份或 DTO;主 Actor 根据身份刷新自己的查询,或者接收已经脱离模型上下文的展示数据。

错误、取消和保存结果也保持结构化:

enum ImportResult: Sendable {
    case saved(PersistentIdentifier)
    case skipped(reason: String)
}

func importOne(
    input: ImportInput,
    store: ImportStore
) async throws -> ImportResult {
    try Task.checkCancellation()

    let id = try await store.insertRecord(
        title: input.title,
        sourceID: input.sourceID
    )

    return .saved(id)
}

不要用信号量、同步队列回跳或脱离生命周期的 Task.detached 作为快捷修复。Swift 6.2 对非隔离异步函数的执行行为也有调整,非隔离异步函数默认更倾向于在调用者 Actor 上运行;如果代码真正需要离开当前 Actor,应明确设计隔离边界,而不是依赖旧项目中的隐式执行假设。(github.com)

迁移决策:一个 target、一个数据模块还是整个项目

老项目不需要一次迁移全部 target。更稳妥的方式是先选择一个拥有独立写入入口、测试数据可控、故障影响有限的数据模块。下面的对比表用于决定第一批范围:

迁移范围 适合条件 优点 主要风险 回滚方式
单个写入用例 能独立构造输入和保存结果 改动最小,容易证明边界 旧调用方仍可能传模型 通过旧 Repository 开关切回
一个数据模块 读写入口已经集中 能统一 DTO 和错误处理 UI 查询与后台写入可能暂时并存 保留旧模块实现和适配层
一个 target 模块边界清楚,依赖少 可独立设置 Swift 语言模式和并发检查 target 间接口需要重新设计 回退 target 版本和依赖锁定
全项目 已有完整回归和统一数据契约 最终结构一致 诊断、性能和回归问题同时出现 通常难以快速定位,不建议作为首批

“只迁移一个 target 或数据模块”是可行的,但前提是边界真实存在。若多个 target 共享同一个 @Model、ModelContext 或 Repository 静态单例,先迁移模块边缘,再清理共享引用。

判断一条链路能否进入首批迁移,可以看四个条件:

  • 输入能否用值类型表达。
  • 写入是否可以由一个 ModelActor 完成。
  • 返回结果能否不用 @Model 实例。
  • 旧实现是否有可切换入口。

满足前三项但没有回滚入口时,先补回滚开关;只有满足全部条件,才提交下一步。

首周迁移:按调用链推进,边改边删除绕过

首周不要按文件夹批量替换。按调用链推进,每次提交只改变一个可观察边界:

  1. 迁移一个新增或更新入口。
  2. 将模型参数替换成值类型或 ID。
  3. 在 Actor 内完成 fetch、修改和 save。
  4. 返回 PersistentIdentifier 或 Sendable DTO。
  5. 跑固定数据集和取消测试。
  6. 记录旧实现与新实现的差异。
  7. 确认后再迁移下一个调用方。

每次提交保留旧实现,但不要让新旧实现共享同一个可变 ModelContext。可以保留如下形式的切换入口:

enum StoragePath {
    case legacy
    case isolated
}

struct FeatureFlags: Sendable {
    let storagePath: StoragePath
}

迁移过程中要逐项审计:

  • @unchecked Sendable:是否真的有不变量证明,能否改成值类型。
  • @preconcurrency:是否只是暂时压低诊断,依赖升级后能否删除。
  • Task.detached:是否需要独立执行器,还是原本就应该使用结构化任务。
  • 扩大化 @MainActor:是否把数据库工作错误地拖进 UI 隔离域。
  • 第三方依赖兼容层:是否只停留在模块边缘。

@unchecked Sendable 的问题不在于它永远不能使用,而在于它把线程安全责任从编译器转给了维护者。若没有明确的状态不变量、访问串行化证明和退出条件,就不应把它当成批量消警工具。

迁移完成证据应包括:编译诊断减少的具体范围、固定输入下的保存结果、取消任务后的上下文状态,以及旧实现切换后的可重复结果。删掉临时绕过后,必须再次运行原始复现样本。

发布前:双工具链和真实并发路径回归

发布前不只看“能否编译”。固定同一份数据集,至少覆盖:

  • 连续新增和更新。
  • 批量导入中途取消。
  • 前后台切换。
  • 多窗口同时读取和写入。
  • 扩展或后台任务与前台 UI 同时访问。
  • 保存失败、重复 ID 和数据迁移异常。

当前交付工具链和计划升级工具链都要跑一遍。Xcode 版本变化可能同时影响 Swift 编译器、SDK、模拟器和调试工具,因此不能只在一台开发机上根据体感判断结果。Xcode 26 官方说明还特别列出了 DerivedData 清理路径;如果怀疑环境污染,应把清理缓存作为复现步骤的一部分,而不是把缓存差异误判为代码修复。(developer.apple.com)

回归记录至少保存四项:

  • 编译诊断:错误、警告和被标记为临时绕过的数量。
  • 活性:主线程采样、任务挂起位置和 UI 操作是否持续响应。
  • 数据一致性:插入、更新、删除和取消后的最终状态。
  • 环境差异:Xcode、SDK、模拟器、缓存和依赖解析结果。

只有第一条链路同时通过编译、活性和数据一致性验证,才复制到其他模块。若后台写入成功但 UI 没有刷新,不要立刻把问题归咎于 ModelActor;先检查 UI 是否消费了正确的 ID、查询是否仍绑定自己的上下文,以及刷新通知是否发生在正确的隔离域。

回滚路径的最低要求

回滚不是保留一份旧代码就结束。最低要求是:

  • 旧实现仍能独立构造自己的上下文。
  • 新旧路径不能同时写入同一条业务操作。
  • 切换入口位于模块边缘,而不是散落在每个调用方。
  • 回滚后可以重新运行原始最小测试。
  • 记录哪些数据已经由新路径写入,避免切换后重复处理。

对大型项目而言,真正可控的单位不是“整个 SwiftData 层”,而是一条有输入、有输出、有保存结果、有回滚点的调用链。

如果当前方案是把所有模型、Repository 和导入任务都压到 @MainActor,短期确实可能少一些编译错误,但会增加主线程阻塞、跨模块耦合和后续拆分成本;如果方案是到处添加 @unchecked Sendable,则会失去编译器对真实边界的约束。相较之下,租赁 ProxyMac 的独立 Mac 环境更适合需要并行验证旧分支、新分支和不同 Xcode 工具链的临时场景,尤其是本机缓存、模拟器状态或开发工具切换会干扰判断时。若需要先了解环境登录、连接和使用方式,可查看 ProxyMac 使用帮助;当第一条 @ModelActor 链路已经通过回归,再根据测试周期评估 ProxyMac 的方案信息。

这不代表租赁适合所有项目。长期稳定重负载、需要固定物理接口或必须由团队长期持有本机资产的场景,更适合自购 Mac。若目标是短期准备 Swift 6.2 维护分支、隔离本机环境差异并完成双工具链验证,独立 Mac 环境通常比在同一台机器上反复清缓存更容易得到可信结论。

为 SwiftData 并发迁移准备一台随时可用的远程 Mac

使用 ProxyMac 远程 Mac,在真实 macOS 环境中快速验证 @ModelActor、后台写入与数据隔离方案。
无需购置本地设备,按需租用 Mac 算力,降低 Swift 6.2 项目迁移与持续测试的成本。