SuperAPI AI 工具集

api-contract-first

编程与开发

查看项目

更新于 10-16 07:26

技能介绍

用途:在编写任何 API 实现之前强制先产出并评审契约,适用于新增 REST 端点、gRPC/protobuf 服务方法、GraphQL 查询/变更/订阅、事件 schema(Kafka、SQS、webhook)以及服务间接口。

主要能力:提供契约编写格式建议(REST 用 OpenAPI 3.x,事件/异步用 AsyncAPI 或 JSON Schema)、契约评审清单(命名与一致性、完整性、版本控制、安全、消费者视角)、审批门禁、按契约实现的原则以及契约测试要求。

使用方式:第一步按技术栈选择格式编写契约并保存到 docs/api/ 或 docs/events/;第二步对照评审清单检查,包括资源名用复数名词、错误响应齐全(至少 400、401、403、404、422、500)、必填与可选字段明确、字段类型与约束定义、分页说明、破坏性变更需新版本、认证与授权范围说明;第三步在实现前完成评审,规划代理必须在实现计划中引用已批准的契约文件;第四步严格按契约实现,若需变更先改契约再重新评审;第五步为每个端点编写至少一个契约测试,用 openapi-validator 等工具校验实际响应是否符合 schema。

限制:资料未提供该技能的具体安装命令、支持的平台、收费方式或运行环境要求;其内容为流程规范与检查清单,不包含可直接执行的完整工具链。