SuperAPI AI 工具集

public-api-design-review

编程与开发

查看项目

更新于 10-16 08:44

技能介绍

用途:对已上线或仍在纸面上的 REST/HTTP API 表面做检查清单式设计评审,关注跨接口一致性而非单个端点的技巧性,目标是让外部开发者觉得整套 API 像同一个团队设计。不适用于 GraphQL 或 gRPC,应分别交给对应的评审技能。

主要能力:先做澄清提问(已发布还是提案、有哪些 OpenAPI 或参考文档、一次性评审还是设计常设流程、消费者是谁与生命周期阶段、遵循哪套规则集、客户端已观察到哪些行为)。评审按八个维度逐项走查:资源建模与 URI 命名、HTTP 方法语义、状态码正确性、字段命名一致性、分页、过滤排序与字段选择、错误响应结构一致性、向后兼容性。另有五项只做存在性与一致性检查,深度交给相邻技能:版本方案、幂等与重试、认证模型、限流信号、文档完整性。

用法:先划定范围并盘点端点,标注为集合型、变更型或两者兼有;若有 OpenAPI 规范且能运行工具,先跑 Spectral 类或 Zally 类静态检查,工具负责机械性问题,人负责语义问题;然后加载 references/review-checklist.md 逐维度走查。发现分两档:Must-change 必须引用成文规则或先例,无规则可引一律归为 Improvement。报告结构为范围抬头(表面、受众、生命周期阶段、引用规则集)、逐维度通过/不通过摘要、发现表(发现、维度、分档、引用规则、建议修复),并附已接受的偏离及其理由。仅当需要设计常设流程时,才进入流程设计步骤。

适用场景:API 对外公开前的评审、/v1 端点一致性审计、团队规模扩张时设计不成为瓶颈的评审流程。

限制:不评审 GraphQL 和 gRPC;不做错误码分类与重试语义等相邻主题的深入设计;所有阈值与基准为校准参考而非定律;必须一次以整个 API 表面为单位评审,孤立评审单个端点看不到一致性问题。