SuperAPI AI 工具集

go-idiomatic-api-design

编程与开发

查看项目

更新于 10-16 00:02

技能介绍

用途:该技能用于设计或演进 Go 包 API,并评审公共 API 的兼容性与惯例。主张从调用方代码向内设计,选择能保持不变量、可无痛演进的最小公共表面。

主要能力:识别调用方、支持的操作与兼容性约束;在选定导出名与类型前先勾勒真实调用点;保持包内聚、命名清晰且不重复包名;优先使用具体实现 API,在消费方定义窄接口;确定零值、可变性、复制、并发与错误契约;评审嵌入、接收者方法集、typed-nil、泛型与选项冲突;仅在语义真正匹配时集成标准接口;用外部测试与可执行示例验证公共表面;检查无意引入的兼容承诺。

使用方式:按任务加载对应文件,例如设计或演进 API 用 guidelines.md 与 workflows/review-public-api.md;选择类型、字段、方法或接口用 references/api-design/rules.md;了解兼容性与方法集用 references/api-design/knowledge.md;查看具体模式用 references/api-design/examples.md。

限制与警戒:不要仅为免写行为而导出字段;不要把提供方接口定义为其方法集的镜像;在真实消费方需要替换前不要接受接口;当标准接口惯例语义出人意料时不要使用;不要声称一致性断言证明了行为;除非每个提升行为都有意为之,不要嵌入公共类型;不要在接口成功路径返回 typed nil 指针。给出依赖版本的建