用途:用于从零设计 REST 或 GraphQL API、评审现有 API 契约的一致性、评估 API 技术与框架、实施版本化策略、设计认证授权流程、编写 OpenAPI/Swagger 规范及开发者文档。
主要能力:
- 契约优先设计:先定义契约再实现,流程为识别用例与消费方需求、建模资源及关系、定义操作(CRUD 与自定义动作)、规定请求/响应模式、记录错误场景、实现前与消费方验证。
- 一致性规范:命名约定(复数名词、kebab-case)、响应封装结构、统一错误格式、分页方式、查询参数模式、ISO 8601 日期时间。
- REST 模式:资源建模与 URL 层级、HTTP 方法语义(GET/POST/PUT/PATCH/DELETE/OPTIONS 的幂等与安全性)、状态码选择(200/201/202/204、400/401/403/404/409/422/429、500/502/503/504)、统一错误响应格式、偏移与游标分页、过滤排序与字段选择。
- GraphQL 模式:类型与连接(Connection/Edge/PageInfo)设计、Query 与 Mutation 设计、输入与载荷类型、N+1 查询防护(DataLoader、复杂度分析、深度限制、持久化查询)。
- 版本化:URL 路径、请求头、查询参数三种方式及推荐的双重方案(主版本走路径、次版本走请求头、Sunset 头提示弃用)。
- 认证:API Key、OAuth 2.0/OIDC 流程(授权码+PKCE、客户端凭证、设备码)、JWT 声明与安全实践。
- OpenAPI/Swagger:规范结构、可复用组件(schemas、parameters、responses)。
使用方式:作为技能加载后,按上述设计序列与检查清单指导 API 设计与评审;资料提供 templates/rest-api-template.md 与 templates/graphql-schema-template.md 两个模板文件。
适用场景:新 API 设计、契约评审、技术选型、版本化与认证方案设计、规范与文档编写。
限制:资料未提供具体安装命令、运行环境要求、收费方式或平台支持信息,暂未提供。