ECC 规则体系下的 Swift 编码风格指南：格式化、不可变性、错误处理与并发实践-北京尧图网络

ECC 规则体系下的 Swift 编码风格指南格式化、不可变性、错误处理与并发实践【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC本文基于 ECCAgent Harness Performance Optimization System规则体系中的 Swift 编码风格规则日语版整理而成。该规则文件位于 ECC 仓库的rules/swift/语言专属规则目录中适用于项目中所有**/*.swift与**/Package.swift文件。读完本文你将掌握一套可直接落地的 Swift 编码规范格式化工具链SwiftFormat / SwiftLint / swift-format的选用、以let与struct为核心的不可变性策略、符合 Apple API 设计指南的命名法、Swift 6 类型化错误处理typed throws写法以及 Swift 6 严格并发检查下的Sendable、Actor 与结构化并发最佳实践。规则文件的定位与适用范围在 ECC 仓库中rules/目录采用通用层语言专属层的组织结构详见 rules/README.mdrules/ ├── common/ # 语言无关的通用原则始终安装 │ ├── coding-style.md │ ├── git-workflow.md │ ├── testing.md │ ├── performance.md │ ├── patterns.md │ ├── hooks.md │ ├── agents.md │ └── security.md └── swift/ # Swift 专属规则 ├── coding-style.md ├── hooks.md ├── patterns.md ├── security.md └── testing.mddocs/ja-JP/rules/swift/coding-style.md是英文版 rules/swift/coding-style.md 的日语翻译两者内容一致并在文件头通过 frontmatter 声明了匹配路径paths: - **/*.swift - **/Package.swift这意味着该规则会在 Agent 处理 Swift 源文件与 SwiftPM 包描述文件时被自动加载。文件开头明确说明此文件扩展了 common/coding-style.md 中的 Swift 特有内容因此它并非孤立规范而是与通用编码风格规则叠加生效的——通用层的 KISS、DRY、YAGNI、文件组织与代码质量清单详见 rules/common/coding-style.md同样适用于 Swift 项目本文将在相应小节中一并展开。格式化SwiftFormat 与 SwiftLint 双工具链规则文件给出了明确的工具分工SwiftFormat负责自动格式化auto-formattingSwiftLint负责风格强制style enforcementXcode 16环境可选地使用捆绑的swift-format作为替代方案这种格式化与 lint 分离的模式是业界主流实践SwiftFormat 负责机械性的排版统一缩进、空行、逗号、运算符两侧空格等而 SwiftLint 负责语义层面的规则检查命名规范、代码复杂度、反模式检测。如果你使用 Xcode 16 及以上的工具链也可以直接用 Apple 官方捆绑的swift-format完成格式化减少第三方依赖。在 ECC 的 Swift 规则体系中这两款工具还被进一步接入到了PostToolUse 钩子中见 docs/ja-JP/rules/swift/hooks.md在~/.claude/settings.json中配置后Agent 每次编辑.swift文件后会自动执行SwiftFormat编辑后自动格式化.swift文件SwiftLint编辑后对.swift文件执行 lint 检查swift build编辑后对变更的包执行类型检查type-check也就是说格式问题不再是代码评审阶段才暴露的事后问题而是在编辑动作发生时就由钩子机制即时拦截与修复形成编辑 → 格式化 → lint → 类型检查的闭环。不可变性let优先与值语义的struct规则对可变性给出了近乎强制的约定优先使用let而非var—— 所有变量先以let定义只有编译器要求时才改为var默认使用值语义的struct只有需要同一性identity或引用语义时才使用class这条规则与 rules/common/coding-style.md 中标记为CRITICAL的不可变性原则一脉相承// Pseudocode WRONG: modify(original, field, value) → changes original in-place CORRECT: update(original, field, value) → returns new copy with change通用层给出的理由是不可变数据可以杜绝隐藏的副作用hidden side effects、显著降低调试难度并让并发安全成为可能。对应到 Swift 语法层面let声明的是常量绑定编译器在编译期即强制不可变任何修改尝试都会直接报错——这是以编译器为守门员的不可变策略struct的值语义意味着每次赋值或传递都是复制而非共享引用函数内对参数的修改不会泄漏到外部调用方天然规避了别名aliasing问题class只在真正需要引用共享、对象同一性如比较或 Objective-C 互操作时使用。在 ECC 的 Swift 模式规则docs/ja-JP/rules/swift/patterns.md中这一理念被进一步延伸为两条具体模式值类型模式——数据传递对象DTO与模型一律使用struct需要建模不同状态时优先使用带关联值associated values的enumenum LoadStateT: Sendable: Sendable { case idle case loading case loaded(T) case failed(Error) }协议导向设计——定义小而聚焦的协议通过协议扩展提供共享默认实现。例如下面这个Sendable仓储协议protocol Repository: Sendable { associatedtype Item: Identifiable Sendable func find(by id: Item.ID) async throws - Item? func save(_ item: Item) async throws }命名遵循 Apple API 设计指南规则要求遵循 Apple API 设计指南并提炼出三条可操作的要点使用处的清晰性Clarity at the point of use——省略不必要的单词让调用点在读起来时意图明确方法与属性按角色而非类型命名——即命名反映做什么/是什么而不是是什么类型。例如读取方法的命名应体现职责如load(id:)而不是暴露底层实现类型常量优先使用static let而非全局常量——将常量收敛到类型作用域内避免污染全局命名空间也便于测试与 mock。这三条与 rules/common/coding-style.md 中的通用命名约定变量/函数camelCase、布尔值用is/has/should/can前缀、类型PascalCase、常量UPPER_SNAKE_CASE配合使用可以形成完整统一的命名体系。错误处理Swift 6 类型化 throws 与模式匹配规则明确要求使用typed throwsSwift 6与模式匹配来处理错误。这是 Swift 6 引入的重要语言特性throws关键字可以携带具体错误类型错误类型信息进入函数签名调用方无需依赖文档或运行时猜测错误种类。规则给出了如下参考实现func load(id: String) throws(LoadError) - Item { guard let data try? read(from: path) else { throw .fileNotFound(id) } return try decode(data) }这段代码展示了三个关键点throws(LoadError)明确声明了错误类型编译器可以在catch分支中提供穷尽性检查exhaustive matching漏掉某个错误情况会直接编译失败throw .fileNotFound(id)通过点语法简写推断出具体错误成员配合枚举的关联值把上下文如id一并携带try? read(from: path)将读取失败转化为可选值再通过guard let提前返回并抛出带有上下文的错误——这是 Swift 中fail fast的典型写法。这条规则与通用层rules/common/coding-style.md的错误处理要求相互呼应始终全面处理错误——在每一层显式处理错误面向 UI 的代码提供友好的错误信息服务端记录详细的错误上下文绝不静默吞掉错误Never silently swallow errors。类型化 throws 正是绝不静默吞错的编译期保障错误类型一旦进入签名调用方就无法假装它不存在。并发Swift 6 严格并发检查与三优先原则规则要求启用Swift 6 严格并发检查strict concurrency checking并明确给出三个优先级跨越隔离边界isolation boundary的数据使用Sendable值类型——Sendable协议标记类型可以安全地在并发域之间传递值类型的struct/enum天然更易满足Sendable约束共享可变状态使用 Actor——由编译器保证串行访问替代手写的锁lock与派发队列DispatchQueue优先使用结构化并发async let、TaskGroup而非非结构化Task {}——结构化并发让任务的父子关系、取消传播与错误处理都遵循清晰的词法作用域避免fire-and-forget导致的悬空任务。ECG 的 Swift 模式规则docs/ja-JP/rules/swift/patterns.md给出了对应的 Actor 模式示例actor CacheKey: Hashable Sendable, Value: Sendable { private var storage: [Key: Value] [:] func get(_ key: Key) - Value? { storage[key] } func set(_ key: Key, value: Value) { storage[key] value } }Actor 的核心理念是编译器帮你上锁storage是 actor 隔离的私有状态所有外部访问都要经过await从而在编译期就消灭数据竞争data race的可能。这与 ECC 技能库中的 swift-actor-persistence 技能一脉相承——该技能专门讲解用 Actor 构建线程安全的数据持久化层以 actor 作为仓储内存缓存与文件落盘全部封装在 actor 内部通过 actor 隔离机制在编译期设计掉数据竞争取代手写锁与 DispatchQueue 同步。技能中同样给出了Sendable泛型约束与 Codable 落盘的具体实现可以作为本文并发规则的进阶阅读材料。依赖注入中的并发考量并发与依赖注入DI也密切相关。docs/ja-JP/rules/swift/patterns.md 建议用带默认参数的协议注入来兼顾生产默认与测试 mockstruct UserService { private let repository: any UserRepository init(repository: any UserRepository DefaultUserRepository()) { self.repository repository } }这种写法让生产环境直接使用默认实现而测试时注入 mock配合协议层声明Sendable约束如前文Repository协议依赖注入在 Swift 6 严格并发模型下同样保持类型安全。更完整的协议注入与 mock 模式可参考技能 swift-protocol-di-testing。配套规则测试、安全与质量清单编码风格并非孤立存在ECC 的 Swift 规则包还提供了配套的测试与安全规范与本文主题直接协同测试docs/ja-JP/rules/swift/testing.md——新测试统一使用Swift Testing框架import Testing以Test与#expect编写Test(User creation validates email) func userCreationValidatesEmail() throws { #expect(throws: ValidationError.invalidEmail) { try User(email: not-an-email) } } Test(Validates formats, arguments: [json, xml, csv]) func validatesFormat(format: String) throws { let parser try Parser(format: format) #expect(parser.isValid) }测试隔离要求每个测试获取全新实例init中 setup、deinit中 teardown测试间不得共享可变状态——这与本文的不可变性/并发原则完全一致。覆盖率采集命令为swift test --enable-code-coverage安全docs/ja-JP/rules/swift/security.md——敏感数据token、密码、密钥必须使用 Keychain Services禁止UserDefaults构建期密钥走环境变量或.xcconfig绝不硬编码密钥反编译工具可轻易提取App Transport SecurityATS默认强制不应关闭外部输入API、深度链接、剪贴板处理前必须校验优先使用带校验的URL(string:)而非强制解包。质量清单rules/common/coding-style.md——通用层在收尾前要求逐项自检代码可读且命名良好函数保持短小50 行文件聚焦800 行典型 200–400 行无超过 4 层的深嵌套错误处理到位无硬编码魔法值用常量或配置无变异采用不可变模式。这为编码风格合规提供了可勾选的验收标准。如何安装与使用这套 Swift 规则ECC 规则支持脚本安装与手动安装两种方式详见 rules/README.md方式一安装脚本推荐./install.sh swift一次可安装多个语言规则集./install.sh swift typescript python。方式二手动安装注意必须整目录复制不要用/*拍平——common 与语言目录存在同名文件拍平会导致语言文件覆盖通用规则并破坏语言文件对../common/的相对引用。# 创建 ECC 规则命名空间一次性 mkdir -p ~/.claude/rules/ecc # 安装通用规则所有项目必需 cp -r rules/common ~/.claude/rules/ecc/ # 按项目技术栈安装语言规则 cp -r rules/swift ~/.claude/rules/ecc/安装后规则通过文件头部的pathsfrontmatter**/*.swift、**/Package.swift在 Agent 处理 Swift 文件时自动生效配合 PostToolUse 钩子中配置的 SwiftFormat / SwiftLint / swift build 自动化流程即可将本文描述的编码风格完整落地到日常开发管线中。小结ECC 的 Swift 编码风格规则以五根支柱构成完整体系格式化SwiftFormat SwiftLint swift-format保证风格统一不可变性let优先、struct默认从源头消除副作用命名Apple API 设计指南提升使用处清晰度类型化错误处理typed throws 模式匹配把错误契约写进签名并发Sendable Actor 结构化并发在编译期消灭数据竞争。这套规则与通用层 KISS/DRY/YAGNI 原则、Swift 模式/测试/安全配套文件、以及swift-actor-persistence、swift-protocol-di-testing技能深度联动既可直接复制进日常 Swift 工程也可作为团队评审与 Agent 编码的自动化约束基线。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

ECC 规则体系下的 Swift 编码风格指南：格式化、不可变性、错误处理与并发实践

相关推荐

智慧供热物联网远程监控系统方案解析

LeetCode 25. Reverse Nodes in k-Group 题解：Go 递归实现 K 个一组反转链表

freeCodeCamp 每日编程挑战深度解析：Challenge 221 Inverted Matrix（矩阵双值反转）

更多资讯

企业电脑监控软件免费试用选型指南：避坑实测路线

Bootstrap 4栅格系统深度解析：Flexbox引擎如何重塑布局

9款AI写作工具助力学术论文高效产出

共享储能电站优化调度模型与工程实践

乙巳年腊月二十“向心行”：年末复盘与新年规划指南

使用 impeccable adapt 完成 iOS / Android 原生界面适配：从重排版到重塑体验的完整指南

今日更新

CopilotKit Vue Demo 与 React Demo 的 Parity 实现指南：路由、运行时端点与交互语义的全框架对齐

Harbor RBAC 实战：db_auth 模式下非管理员用户管理项目成员的完整验证与权限模型解析

STM32平衡车纯平衡程序从拆包到参数整定的完整调试指南

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？