SuperAPI AI 工具集

api-design

编程与开发

查看项目

更新于 10-16 09:31

技能介绍

用途:该技能用于在设计 API、定义接口契约与处理版本控制时提供规范指导,覆盖 REST、GraphQL、gRPC 三种风格。

主要能力:提出契约优先原则,规范先行;REST 部分给出资源命名、HTTP 方法与状态码对应、RFC 7807 错误响应、游标分页、URL 版本控制及弃用头(Sunset、Deprecation、Link)写法;幂等性方面要求 PUT/DELETE 幂等,POST 使用 Idempotency-Key。GraphQL 部分强调领域驱动模式、限制嵌套、用 @key 标记联邦实体、Relay 风格分页与联合类型表达类型化错误,并建议用 DataLoader 避免 N+1。gRPC 部分给出 proto3 定义、Unary 与三种流式 RPC、Google 错误模型、截止时间与重试策略。附有选型对照:公开 API/MVP 用 REST、前端驱动或移动端用 GraphQL、微服务内部用 gRPC、实时数据用流式订阅。还列出速率限制响应头与 429 返回格式,以及设计、功能、文档、运维四类检查清单。

使用方式:作为设计阶段的参考规范,配合资料中提供的模板文件使用,如 templates/openapi/openapi.yaml、templates/graphql/schema.graphql、templates/grpc/service.proto,以及 reference/rest.md、reference/graphql.md、reference/grpc.md、reference/comparison.md 深入阅读。

限制:资料中提及“不做向后兼容,删除而非弃用”,与其他版本控制建议存在张力,实际采用需自行判断;未提供具体工具安装命令、收费标准或运行环境要求。