SuperAPI AI 工具集

api-and-interface-design

编程与开发

查看项目

更新于 10-21 06:25

技能介绍

用途

该技能在需要设计或变更公共 API、路由、CLI 参数或模块边界时使用,不适用于远程、凭据、发布、部署或不可逆变更。

主要能力

  • 先界定范围:明确要设计或变更的具体接口及其属于新建还是变更,并在代码库中搜索列出全部已知调用方,无法检查的调用方记为未迁移风险。
  • 先写契约再实现:为每个操作、字段或参数记录名称、输入类型、输出类型、错误情形与副作用,并显式说明语义,包括是否幂等、顺序、可空性、编码与并发。
  • 变更分类:对既有接口的变更判定为破坏性或非破坏性;若为破坏性,则将新契约、逐调用方迁移和旧路径移除设计为一次改动。
  • 信任边界校验:按文档化契约校验输入,畸形输入以文档化错误拒绝,不静默转换或为未文档化值设默认。
  • 调用方迁移:更新每个调用方使其通过新签名编译或类型检查,更新后才记为已迁移。
  • 清理旧路径:删除旧签名、别名、再导出与弃用入口,不保留兼容层、别名或回退;以搜索旧签名无活跃引用作为完成判据。

使用方式

按技能规定的流程推进:界定范围并列出调用方,编写包含语义与错误的契约文档,判定变更类型并设计一次性切换,在信任边界校验输入,逐个迁移调用方,最后删除旧路径并搜索确认无残留。失败处理上,若调用方无法检查或更新则停止并记为阻塞风险;若语义无法具体表述则停止并请求补充规格而非猜测;部分迁移的结果不可交付,应保持草稿未提交并报告剩余调用方与未解决语义。回滚方式为丢弃未提交草稿,调用方修改与旧路径恢复同属该草稿,可经版本控制恢复。

适用场景

适用于本地可回滚的接口设计与切换工作,例如新增公共 API 端点、调整路由、变更 CLI 参数、重划模块边界,以及在破坏性变更中一次性完成新契约、调用方迁移与旧路径删除。

限制

  • 权威范围仅限可回滚的本地操作:只写指定的本地接口定义与契约文档、编辑调用方文件、在切换时删除旧路径;不进行远程变更、凭据/付费/发布/部署变更,也不重写版本控制历史。
  • 副作用限于写接口定义与契约文档(先于实现)、编辑调用方并删除旧路径(切换时),不执行构建、发布或远程变更。
  • 若存在无法检查或更新的调用方,或字段语义无法具体表述,变更即视为未完成,不得宣称满足完成条件。

输出

包含每个操作、字段与参数语义和错误的契约文档;已迁移调用方列表;搜索旧签名无活跃引用的确认;若被阻塞,则输出未迁移调用方列表与未解决语义列表以替代完成确认。