SuperAPI AI 工具集

sota-swift

编程与开发

查看项目

更新于 11-07 05:16

技能介绍

用途

SOTA Swift(2026)为 Claude 提供专家级规则,用于编写和审计生产环境的 Swift 代码,适用于任意目标平台。其定位是:Swift 首先是一门语言,其次才是 Apple 平台工具链,因此 Linux 上的 Vapor 服务、命令行工具和 iOS 应用共用同一套规则。规则明确把平台相关事项分流到其他技能:应用生命周期、商店审核、Keychain、推送和离线同步交给 sota-mobile;容器交给 sota-sandboxing;命令行工具的参数、输出和退出码交给 sota-cli-ux;遥测交给 sota-observability。

版本基线

资料说明,swift.org 并未公布旧版 Swift 的生命周期终止或支持窗口政策(检索时间为 2026-10-07),最接近的书面标准是 Swift Server Workgroup 的毕业标准:“30 天内支持新的 GA 版本 Swift”,以及“为至少一个上一主版本记录支持策略”。因此建议固定构建所用工具链,在 swift.org 核对最新版本,并把语言模式作为关键界线:Swift 6 模式会把数据竞争安全变为编译错误。文中各特性均标注了引入版本。

BUILD 模式

  • 在 Package.swift 中声明工具链和语言模式(swift-tools-version: 6.x、swiftLanguageModes:;swiftLanguageVersions 自 6.1 起弃用,SE-0441),并在 CI 中固定工具链。
  • 按工作内容阅读对应规则文件:任何含 async、actor 或共享状态的代码都适用并发规则(rules/03);涉及输入、文件、进程、SQL 或网络的代码适用安全规则(rules/05);服务端代码还需阅读 rules/06。
  • 编写值类型、穷尽枚举和非可选直线代码(rules/01);保持公共接口小而可演进(rules/02)。
  • 最后自审:按每个已加载文件的 Audit 清单对照改动,再核查路由原则 5(滥用控制、传输、测试、日志)。

AUDIT 模式

  • 覆盖范围:AUDIT 模式下每个 rules/ 文件的 Audit 清单都适用;只有写明理由才可标记为不适用,不能因为“要检查的东西不存在”就跳过文件,因为这种缺失本身可能就是发现。
  • 侦察:检查 Package.swift(工具版本、语言模式、unsafeFlags、插件、宏、二进制目标)、Package.resolved、CI 配置、所用服务端框架。
  • 运行已安装的工具(不要未经请求就安装;缺失项询问操作者):以 Swift 6 模式并启用 -warnings-as-errors 的编译器、SwiftLint、swift build --sbom-spec(6.4+)、依赖扫描器(rules/09)、CI 中可用的 CodeQL Swift 查询。
  • 逐一走查适用的规则文件 Audit 清单,每个探测项都是可执行的 grep。
  • 按规范格式报告;严重级别按下表,链式关闭遵循 sota 路由。

严重级别约定

  • 致命(Critical):如用请求输入通过 \(unsafeRaw:) 拼接 SQL;生产客户端设置 certificateVerification: .none;用插值输入执行 /bin/sh -c;对不可信字节调用 NSKeyedUnarchiver.unarchiveObject(with:)。
  • 高(High):如可达状态上 nonisolated(unsafe) / @unchecked Sendable 背后的数据竞争;未认证路由组缺少守卫中间件;会话 cookie 保持 Vapor 默认的 isSecure: false;发布调试构建(把原始错误文本发给客户端);在无沙箱运行插件的 Linux CI 上使用未审查的插件/宏依赖。
  • 中(Medium):如对输入派生值使用 try!/!/as!;用 Double 表示金额;无界 AsyncStream 缓冲;无理由的 Task.detached;对输入使用易受 ReDoS 攻击的正则。
  • 低(Low):如写路径上的 try?;热路径上的 any P;缺少 final;两阶段初始化之外的 IUO。

发现格式

file:line | rule | severity | effort | fix,即路由规范行;每个保留的发现再展开为路由 rules/03 §2 的证据块。

规则索引

  • rules/01-idioms-and-errors.md:编写任何 Swift 时阅读——值类型与类、枚举、可选值与强制解包、throws/类型化 throws/try?、整数溢出与金额、日期与时钟。
  • rules/02-api-design.md:设计模块或包 API 时阅读——协议与泛型(some/any)、访问控制(public/package)、库演进与 @frozen、弃用、SemVer。
  • rules/03-concurrency.md:涉及 async、actor、Task、Sendable 或共享可变状态时阅读——Swift 6 模式、隔离逃生舱、重入、结构化并发、取消与超时、流与背压。
  • rules/04-memory-and-unsafe.md:循环引用、weak/unowned、资源所有权(defer、~Copyable)、unsafe 指针、C 互操作、严格内存安全。
  • rules/05-security.md:输入、文件、进程、SQL、HTTP、加密、解码、正则、日志、密钥——语言层面的安全表面。
  • rules/06-server-side.md:Vapor/Hummingbird/SwiftNIO 服务——认证中间件顺序、cookie 与会话默认值、发布与调试、请求体限制、错误响应、Linux Foundation。
  • rules/07-performance.md:先做性能剖析、分配、ARC 开销、存在类型、写时复制、CI 中的基准测试。
  • rules/08-tooling-ci-testing.md:工具链固定、警告即错误、SwiftLint/swift-format 及所有抑制项、Swift Testing/XCTest、sanitizer、不稳定测试。
  • rules/09-supply-chain.md:Package.resolved、版本要求、注册表与包标识、插件与宏(构建时代码)、二进制目标、SBOM、漏洞扫描、引入软件包。

十条不可妥协项

  1. 全部一方代码使用 Swift 6 语言模式;每个 nonisolated(unsafe)、@unchecked Sendable、@preconcurrency 和 unowned(unsafe) 都要有注释说明其安全不变式。
  2. 对输入派生的值不使用 !、try! 或 as!;改用 guard let/throw。
  3. 公共 API 使用无类型 throws;类型化 throws 仅限封闭边界内部。
  4. 优先结构化并发;每个非结构化 Task 都有负责取消它的所有者;长循环检查取消。
  5. 无循环引用:被 self 存储的逃逸闭包以 [weak self] 捕获。
  6. SQL 用绑定,绝不拼接:输入不进入 \(unsafeRaw:)/unsafeSQL:;进程使用参数数组,绝不用 /bin/sh -c。
  7. TLS 校验保持开启;NIOSSL 客户端显式设置最低 TLS 1.2。
  8. 发布 release 构建(swift build -c release);生产行为绝不依赖调试构建的 #if DEBUG 或 Vapor 编译期 isRelease。
  9. 提交 Package.resolved,CI 中用 --force-resolved-versions 解析;把插件和宏当作构建时代码审查——在 Linux 上它们无沙箱运行。
  10. CI 中警告即错误,每个 SwiftLint/编译器抑制项都可见且有理由。

适用场景与限制

本技能适合在编写或审计生产 Swift 代码时作为规则依据,覆盖 idiom、API 设计、并发、内存安全、安全、服务端、性能、工具链与供应链。资料强调 Swift Evolution 提案状态(swift.org/swift-evolution)是判断特性是否已发布的首要来源,“已接受”不等于“已实现”;文中事实均带验证日期,固定版本或引用默认值前应重新核对。平台生命周期、Keychain、推送、容器、CLI 交互与遥测等事项不在本技能范围内,需交由相应技能处理。