Swift API 设计指南

需要解决的问题

在 Swift 开发中，API 设计常因缺乏统一标准而变得混乱：不同模块的命名风格不一致、返回类型随意、错误处理各异，导致调用方难以理解和维护。团队协作时，新人容易写出不符合约定的接口，代码审查也缺少客观依据。

技能如何工作

该技能提供一套 Swift API 设计规范，覆盖以下关键实践：

• 命名约定：明确参数、方法、属性的命名规则，例如使用 camelCase 而非 snake_case。
• 返回类型：建议使用 Result 或可选类型来表达可能失败的操作，避免返回隐式解包可选值。
• 错误处理：定义统一的错误枚举结构，确保错误信息可追溯、可分类。
• 可读性优先：强调 API 的自解释性，减少对文档的依赖。

使用该技能时，开发者可参考其子技能文件中的具体规则，在设计接口时逐条对照，快速识别不符合规范的写法。

适用边界与注意点

• 适用于 Swift 5.0 及以上版本。
• 不涉及 UIKit/SwiftUI 的 UI 组件设计，仅关注 API 层面的接口规范。
• 对于已有大量历史代码的项目，建议逐步迁移而非一次性重构。
• 不同团队可能有自身偏好，可在此基础上裁剪适配。