该页面是一个名为 write-swift 的技能说明,用途是指导如何“以 Swift 语言希望被书写的方式”编写现代 Swift 代码,内容更新至 Swift 6.4 版本。工具链基线为 Swift 6.3(截至 2026 年 8 月的当前版本),除标注 ⚠ 的未发布 Swift 6.4 特性外,文中内容均可在 6.3 上编译。并发相关建议假定使用 Swift 6.2 模型;若项目使用 6.1 或更早版本,则第 3 节中 async 与 @concurrent 的规则不适用。
整体主线是:Swift 是一种渐进式披露的语言。应从最简单、最静态、最单线程且可行的方案开始,只在能够指出具体理由时才引入动态性——并发、引用语义、存在类型、非安全指针。文中给出一个默认层级:数据优先用 struct/enum,只有需要身份、共享或继承时才降到 class;抽象优先用具体类型,只有跨类型出现重复代码时才引入协议;多态优先用泛型 some P,只有需要异构存储时才用 any P;执行优先在主 actor 上同步进行,只有性能分析显示卡顿才依次引入 async、@concurrent、actor;内存优先用 Array、String,只有性能分析显示成本过高才用 InlineArray、Span;安全优先用安全 API,只有 C 互操作或经测量的热路径才用 Unsafe*。
第 1 节讲用值类型建模:默认使用 struct 和 enum,class 仅用于身份、共享可变状态、继承或资源生命周期;默认 let,仅在需要修改时用 var;struct 持有可变引用类型属性会破坏值语义,应保持引用类型不可变、只暴露转发计算属性,或将其作为私有存储属性配合写时复制;写时复制通过将 final class 包裹在 struct 中并在修改前检查 isKnownUniquelyReferenced(&storage) 实现;enum 用于固定集合和互斥状态,可把多个可选存储属性替换为单一 enum State,使非法组合无法表示;非可复制类型(~Copyable)表达唯一所有权,用 consuming 标记终结方法,参数所有权可显式声明为 borrowing、consuming 或 inout/mutating。
第 2 节讲错误与可选值:可恢复错误用 throw,程序员错误用 precondition/fatalError;带关联值的 enum 最适合作为错误类型;用 guard 处理错误条件,用 if let 做普通解包;类型化 throws(throws(MyError))适用于内部函数、错误转发泛型代码和受限环境,公共 API 宜保持非类型化 throws;仅在能说明不变式时强制解包,优先使用带消息的 #require/precondition。
第 3 节讲并发:代理最容易出错的地方,因为模型在 Swift 6.2 发生变化。应从应用完全运行在主线程开始,按顺序渐进:主 actor 单线程 → async/await 隐藏延迟 → 仅在 Instruments 显示卡顿后用 @concurrent 移走昂贵工作 → 仅在主 actor 状态过多导致频繁跳转时用 actor。应先开启正确构建设置:启用 Approachable Concurrency;应用模块和面向 UI 的模块设置 Default Actor Isolation 为 MainActor(包中为 swiftSettings: [.defaultIsolation(MainActor.self)]);通用库不应设为主 actor 默认。Swift 6.2 的规则变化是:标记 async 不会把函数移出当前 actor,它在被调用处运行;@concurrent 总是切换到并发线程池;nonisolated 在调用处运行,是库 API 的合适默认;两者都不加则留在调用方 actor。应先性能分析再卸载;不要为琐碎工作创建任务;每个端到端操作一个任务;await 是挂起点,会破坏原子性,每次 await 后应重新检查假设,不得跨 await 持有锁或依赖线程本地存储。actor 保证互斥而非事务,同步方法内修改状态才是事务边界,async 方法应保持薄并组合同步事务操作;actor 不保证 FIFO。
第 4 节讲 Sendable 与数据共享:Sendable 标记可跨隔离域安全共享的类型,编译器在任务和 actor 边界检查;非公开值类型在存储可 Sendable 时自动推断,公开类型永不自动推断;actor 和 @MainActor class 隐式 Sendable;多数模型类应既非 @MainActor 也非 Sendable,需要离开主 actor 时用 nonisolated;非 Sendable 对象在发送方停止使用后可跨域传递;仅真正跨域的函数类型才标 @Sendable;@unchecked Sendable 保留给有真实内部同步的类型。遇到数据竞争错误时按顺序处理:不要共享、改为 Sendable 值类型、隔离到 actor、最后才用 Mutex/Atomic 或 @unchecked Sendable。全局与静态变量是常见错误源,优先顺序为 let、@MainActor、Mutex、nonisolated(unsafe)。桥接旧回调 API 可用 @MainActor 标注代理协议,或用 nonisolated + MainActor.assumeIsolated { },@preconcurrency 是同一做法的简写。
第 5 节讲结构化并发:优先结构化任务(async let、任务组),其作用域类似局部变量,自动等待并继承取消、优先级和任务本地值;非结构化任务(Task { }、Task.detached)不自动获得这些。async let 用于固定数量的并发子任务;withTaskGroup 用于动态数量,用 withDiscardingTaskGroup 处理无返回值的子任务;Task { } 仅用于生命周期不契合作用域的工作;Task.detached 几乎不用。取消是协作式的,需要主动检查 Task.isCancelled 或 try Task.checkCancellation();对挂起中的工作使用 withTaskCancellationHandler,其处理程序立即并发运行,所触状态需真实同步。应限制并发数量,不要对无界列表每项扇出一个子任务。@TaskLocal 可沿任务树传递上下文。桥接回调用 withCheckedContinuation / withCheckedThrowingContinuation,约定每条路径恰好恢复一次。AsyncSequence 用 for await / for try await 迭代,可用 AsyncStream / AsyncThrowingStream 适配回调或代理 API。
第 6 节讲 SwiftUI 中的并发:View 及其含 @State 的内容均 @MainActor 隔离,几乎无需手写 @MainActor;SwiftUI 会有意在主线程外运行部分代码,信号是 API 签名中的 @Sendable(如 visualEffect、Shape.path(in:)、Layout 要求、onGeometryChange),遇到隔离错误时应在闭包捕获列表中复制所需值而非发送 self;SwiftUI 动作回调有意为同步,时间敏感的 UI 更新应在同一帧的同步回调中完成,仅将后续长时间工作放入 Task;可在 UI 与异步工作的接缝处放置状态。
第 7 节讲协议与泛型:不要从 class 开始,也不要从协议开始;工作流是先写具体类型,发现跨类型重复代码后提取共享能力为协议,再针对协议写泛型代码;无按类型定制的协议是浪费,若所有实现都用同一默认实现,应改为对已有协议的约束扩展;优先组合而非继承,若协议中只有部分操作适用于某类型,不要细化协议,而应包裹在泛型 struct 中并只暴露需要的 API。