SuperAPI AI 工具集

swift-api-design-guidelines

编程与开发

查看项目

更新于 10-16 05:52

技能介绍

用途:本技能聚焦 Swift 声明命名、参数标签、mutating 与 nonmutating 方法对、协议命名、大小写、重载清晰度以及文档注释,用于设计或评审 Swift API。语言与类型系统机制、并发语义、lint 配置、项目与文件命名不在范围内,应分别交由 swift-language、swift-concurrency、swiftlint 及相关架构或 UI 技能处理。

主要能力与规则:调用点测试要求把每处调用当作句子阅读,保留能说明参数角色的词,删除仅重复类型或声明上下文的词;按首个适用规则选择标签,如值保持型转换初始化器省略首个标签、不可区分同类值省略同类标签、首参数补全基础名短语、参数开启介词短语时用该介词作标签、一般情况用基于角色的标签。副作用方面,可变操作用祈使动词,非可变结果用名词或分词,名词操作返回值用名词、可变形式用 form 加名词,工厂方法用 make,布尔属性与方法按断言命名。命名方面按角色而非类型命名变量与参数,使用领域术语并一词一义,避免非约定缩写;描述事物的协议用名词,能力协议用 -able、-ible 或 -ing 形式;有自然 self 时优先方法或属性;避免仅靠返回类型区分的重载。文档方面,公开 API 应简述用途、参数、返回值、抛出的错误、副作用及相关复杂度,函数摘要说明做什么,类型与属性摘要说明是什么,非常量复杂度需标注。

使用方式与限制:资料提供评审清单与常见错误,如省略参数标签、违反可变命名规则、在标签中重复类型、布尔命名写成命令、仅靠返回类型重载等;重命名公开 API 时需检查访问级别、协议要求、生成接口、调用点并考虑弃用或转发期。具体安装命令、运行步骤与价格暂未提供,且应验证版本相关语言行为。