dev-api-design

API 设计

使用此技能进行 REST、GraphQL、gRPC、tRPC、AsyncAPI 和面向 Agent 的接口的契约优先 API 设计。它负责契约选择、身份验证边界、版本控制、错误、分页、速率限制、幂等性和验证；不能替代后端实现或安全审查。

风格决策表

API 风格	适用场景	不适用场景	规范产物
REST + OpenAPI	公共 API、广泛的工具兼容性、可缓存资源	以流式处理为先的服务契约	OpenAPI 3.x
GraphQL	复杂的、由客户端驱动的查询形态，多团队共同负责 Schema	简单的 CRUD、缓存至关重要、单团队	GraphQL SDL
gRPC	内部服务、双向流、类型要求严格的边界	公共互联网消费者、浏览器原生客户端	protobuf
tRPC	共享服务端和客户端的 TypeScript 单体仓库	非 TypeScript 技术栈、公共第三方消费者	TypeScript 类型
AsyncAPI + webhooks	事件驱动契约、发布/订阅、推送通知	同步请求-响应	AsyncAPI 3.x
MCP 工具层	Agent 或大模型是主要消费者	仅面向人工的客户端	MCP 工具 Schema

快速参考

API 风格	加载内容
REST + OpenAPI	references/restful-design-patterns.md、references/openapi-guide.md
GraphQL	references/graphql-patterns.md
gRPC	references/grpc-patterns.md
tRPC	references/trpc-patterns.md
AsyncAPI 和 webhooks	references/asyncapi-patterns.md、references/webhook-patterns.md
核心通用内容	references/error-handling-patterns.md、references/authentication-patterns.md、references/pagination-filtering.md、references/rate-limiting-patterns.md、references/api-testing-patterns.md

契约审查清单

交接前，对每份 API 契约执行以下检查：

• 存在规范的规格说明产物（OpenAPI、AsyncAPI、protobuf、GraphQL SDL 或 MCP Schema）
• 明确兼容性和版本控制模型：渐进式变更、URL 路径（/v1/）、标头或内容类型协商
• 在规格说明或关联文档中写明弃用时间线；Deprecation 标头采用 RFC 9745 的 @<unix-seconds> 格式，Sunset 遵循 RFC 8594
• 错误模型：对于 REST/HTTP，使用 RFC 9457 Problem Details，并提供稳定的 type URI；客户端需要时，使用应用程序 code 扩展；对于 GraphQL、gRPC 和事件，在各自的原生契约中定义错误
• 身份验证边界：哪些端点需要哪些作用域；令牌类型（JWT、不透明令牌）；撤销途径
• 分页：高基数场景使用基于游标的分页；仅对规模小且稳定的数据集使用偏移量分页
• 速率限制：使用 IETF httpapi 的 RateLimit / RateLimit-Policy 字段，或记录在文档中的旧版 X-RateLimit-* 三元组；429 响应包含 Retry-After。IETF 字段在不同草案版本间的形式有所变化：请在 IETF datatracker 上查阅当前修订版本和 RFC 状态，采用该修订版本中的语法，并在规格说明中注明修订版本
• 幂等性：POST/PATCH 操作须说明幂等键，或明确标记为非幂等；无论 IETF Idempotency-Key 标头处于何种状态（请检查 datatracker），规格说明都必须定义键的作用范围、保留期限和重复使用键时的响应
• 长时间运行的任务：使用 202 + Location 轮询 URL；state 枚举中明确列出终止状态
• Webhooks：HMAC 签名；重放保护；负载中包含 trace_id
• 破坏性变更检测：在 CI 中配置 oasdiff 或等效工具
• 契约测试：接入 Schemathesis（基于属性）或 Pact（由消费者驱动）

工作流

1. 根据上方的决策表选择 API 风格。
2. 定义规范的契约制品。
3. 执行契约审查清单。
4. 添加契约验证、破坏性变更检测和文档。
5. 交接规范、示例和发布说明。

按变更类别提供兼容性证据

在判定契约兼容之前，先对每项变更进行分类：

变更类别	所需证据
结构变更	Schema 差异，以及生成的客户端编译通过或消费者契约测试
结构稳定的语义变更	变更前后示例，以及明确命名的行为断言
默认值、顺序、配额或超时变更	近似生产环境的消费者测试和发布说明
移除或收窄	使用情况证据、弃用期，以及回滚方案或兼容性垫片

对于提供方/消费者部署，应根据消息方向、发生变更的载荷一侧，以及消费者的实际容忍度，推导安全的部署顺序。对于新的可选请求能力，应先发布提供方支持，再由消费者发送该能力。对于响应枚举/事件扩展，或消费者可能拒绝未知字段或变体的情况，应先发布并验证具备容错能力的消费者，再由提供方发出新值。对于移除操作，应先发布消费者，确认旧字段的流量已消失，再移除提供方行为。应验证相关消费者的实际行为，而不是根据 Schema 的可加性推断安全性；仅有通过的 Schema 差异不足以证明语义兼容性或部署顺序安全。

其他参考

• 后端实现：software-backend
• AppSec 审查与身份验证强化：software-security-appsec
• 全系统架构：software-architecture-design
• 发布与迁移顺序：dev-workflow-planning

默认做法

• 在实现或代码生成之前定义契约。
• 对需要响应正文的 REST/HTTP 错误使用 RFC 9457 Problem Details；对其他 API 风格定义原生错误结构。
• 在规范中明确版本管理、弃用、幂等性、分页和速率限制。
• 对 HTTP 或事件驱动接口，优先采用 OpenAPI 3.x 或 AsyncAPI 作为规范来源；固定使用流水线中所有验证器、检查器和生成器均支持的最新次要版本。
• 将 Agent API 视为具有明确副作用的领域契约，而不是随机端点的薄封装。
• 当 Agent 是主要消费者时，使用 MCP 作为工具暴露层。其授权模型基于 OAuth 资源服务器标准（RFC 9728 Protected Resource Metadata、RFC 8707 Resource Indicators），但会话、握手和身份验证要求会随规范修订而变化：在围绕会话或 initialize 握手进行设计之前，请前往 modelcontextprotocol.io 查阅当前修订版。参见 references/llm-agent-api-contracts.md。

版本管理策略表

方法	使用场景	破坏性变更门槛
URL 路径版本管理（/v2/）	公共 API、客户端安装基础广泛	在 CI 中运行 oasdiff --fail-on ERR
Header 版本管理（API-Version: 2）	内部 API、频繁迭代	每个 PR 都运行 oasdiff
内容类型协商	超媒体或由媒体类型驱动的 API	人工审查 + 测试
演进式（GraphQL、gRPC）	团队负责 Schema，并运行内省工具	GraphQL Inspector / protobuf 兼容性

专家判断

版本策略——根据客户端由谁控制来选择，而不是根据团队偏好。

• 如果你无法控制每一个客户端（公共 API、第三方集成方、无法强制更新的移动应用），请发布版本策略和支持期限，并根据观察到的使用情况和迁移准备时间来制定；你无法在不通知的情况下迁移调用方。
• 如果你控制每一个客户端（内部服务网格、使用生成式客户端的单体代码库），优先采用渐进式兼容（添加字段、先弃用再移除），而不是版本化——新版本号会带来你无需承担的协调成本。
• 如果每个账户或请求都可以独立固定行为，按日期划分的版本会很有用。如果请求未指定版本，应解析为文档中说明的固定默认版本，而不是在不通知的情况下升级调用方，并在响应头中回显解析出的版本。
• 绝不要让“渐进式演进”成为跳过兼容性检查的借口——GraphQL 和 gRPC 仍需要由 CI 强制执行架构差异检查（GraphQL Inspector、buf breaking）；“不做版本化”不等于“不讲规范”。

规则：当 Claude 编辑匹配的文件时，rules/api/contracts.md 会加载此不变量。

识别破坏性变更的直觉——架构差异工具无法从结构上捕获的内容：

以下情况都是 Hyrum 定律的体现：API 的消费者足够多时，每一种可观察到的行为——而不仅仅是文档中描述的架构——都会成为事实上的契约，无论你是否曾作出承诺。（同一定律也适用于架构部署顺序，而非 API 表面，参见 software-database-design/references/migration-strategies.md。）因此，架构差异检查结果干净并不能证明兼容：

• 形状不变的语义变更：收紧现有枚举允许的值、缩小原本宽松的验证规则范围，或在保持字段类型不变的情况下改变字段的含义——oasdiff/buf breaking 会报告差异为零。
• 行为默认值：更改默认排序顺序、默认页面大小或默认超时时间，会破坏依赖默认值的调用方，即使架构未变。
• 跨字段耦合：某个字段从可选但会被忽略变为可选但会被强制执行（例如，以前只用于展示的 region 字段现在会影响路由）。
• 收紧速率限制和配额：从架构角度看，这不算契约破坏，但对生产流量的影响与移除字段相同——对待配额变更时，应遵循与移除字段相同的弃用通知规范。
• 错误代码重新分类：将某种情况的代码从 404 改为 410，或从通用的 code 改为更具体的代码，会破坏按旧代码进行模式匹配的客户端，即使 Problem Details 的形状没有变化。
• 将自动差异检查（oasdiff、GraphQL Inspector、buf breaking、Pact）视为最低要求，而非上限——同时由了解调用方实际依赖内容的人审查变更日志。

Hyrum 定律的表述改编自 addyosmani/agent-skills（MIT），提交 7676817，2026-08-09。 GraphQL、gRPC 或事件驱动契约不适用的情况：

• 对于只有一种客户端形态的简单 CRUD、需要 HTTP 缓存语义的团队（GraphQL-over-HTTP 规范要求支持 POST，但 GET 是可选的，因此许多服务器只接受 POST；要实现 HTTP 缓存，就需要 GET 加持久化查询），以及单团队负责、无法发挥查询灵活性优势的场景，GraphQL 都不适用——你会平白承担 N+1 风险、查询复杂度 DoS 攻击面和联邦工具链成本，却不给客户端带来任何好处。
• 原生 gRPC 不适合作为浏览器客户端的默认选择，因为浏览器需要 gRPC-Web 或兼容的传输层。对于公开的第三方集成方，还要考虑 protobuf 工具链和传输支持；如果广泛的 HTTP 互操作性和可发现性更重要，应选择 REST+OpenAPI。
• 当调用方需要针对特定请求立即获得可关联的答复时，AsyncAPI/事件契约并不适用——通过发布/订阅强行实现请求/响应工作流，会增加关联 ID 管理负担和超时歧义，而普通的同步 HTTP 可以避免这些问题。
• 如果团队中没人能说出所选风格解决的具体延迟预算、客户端平台限制或多团队协作问题，那就说明这项选择追逐的是潮流，而非实际需求。

常见陷阱

• 为了架构潮流而非实际客户端、延迟或互操作性限制选择 GraphQL、gRPC 或 AsyncAPI。
• 设计顺利路径上的资源，却没有明确说明幂等和重试方案，无法应对重复请求或部分失败的请求。
• 将身份验证问题含糊处理，直到实现阶段才着手，导致各端点的执行方式不一致。
• 复用会将内部存储语义泄露到公开契约中的分页模型。
• 将 Webhook 或事件投递视为可靠推送，却没有签名验证、重放保护或消费者背压机制。
• 实现后再从代码生成规范，却称其为契约优先。
• 将任意内部端点包装成 Agent API，却没有稳定的副作用、身份验证和验证规则。

导航

核心模式：

• references/restful-design-patterns.md — HTTP 方法语义、URL 结构、幂等性
• references/pagination-filtering.md — 游标与偏移量、过滤契约
• references/error-handling-patterns.md — RFC 9457、错误分类
• references/authentication-patterns.md — OAuth 2.1、JWT、API 密钥、mTLS
• references/rate-limiting-patterns.md — 标头、429 处理、突发流量策略 特定风格：
• references/api-design-best-practices.md — 跨风格的 DX 与治理
• references/versioning-strategies.md — 破坏性变更检测、弃用
• references/api-security-checklist.md — OWASP API Top 10 检查清单
• references/graphql-patterns.md — Schema 设计、联邦，以及何时采用 supergraph
• references/grpc-patterns.md — protobuf 设计、流式传输、截止时间
• references/trpc-patterns.md — TypeScript 端到端类型共享
• references/openapi-guide.md — OpenAPI 3.x 编写、Lint、打包
• references/openapi-32-arazzo-101.md — OpenAPI 3.2 相较于 3.1 的新增内容（流式类型、QUERY 方法、OAuth 流程）以及 Arazzo 多步骤工作流链；指定多次调用的 API 序列或采用 3.2 功能时加载
• references/asyncapi-patterns.md — 事件驱动契约、发布/订阅
• references/webhook-patterns.md — HMAC 签名、重放保护、交付保证
• references/real-time-api-patterns.md — SSE、WebSocket、长轮询的权衡
• references/api-testing-patterns.md — 契约测试、基于属性的测试、Schemathesis
• references/llm-agent-api-contracts.md — MCP 集成、AX 设计、Agent 优先模式、LLM 消费规则（汇总统计端点、优先语言的搜索、通过精简负载控制准确性）

资源和模板：

• assets/openapi-template.yaml
• assets/spectral-ruleset.yaml — 用于 OpenAPI 的自定义 Spectral Lint 规则集
• assets/oasdiff-ci.yml — 用于通过 oasdiff 检测破坏性变更的 CI 工作流
• 全栈框架脚手架（FastAPI、Express、Django REST、Spring Boot）属于实现，而非契约设计——已移至 software-backend：assets/python/template-python-fastapi-sqlalchemy.md、assets/nodejs-express/template-nodejs-express.md、assets/python-django/template-python-django-rest.md、assets/java/template-java-spring-boot.md
• assets/cross-platform/api-patterns-universal.md
• assets/cross-platform/template-api-governance.md
• assets/cross-platform/template-api-design-review-checklist.md
• assets/cross-platform/template-api-error-model.md
• data/sources.json

相关技能：

• software-backend、software-security-appsec、data-sql-optimization、qa-testing-strategy、qa-observability、docs-codebase、docs-ai-prd、dev-workflow-planning、software-architecture-design

经验循环

当以往的决策或陷阱与当前任务相关时，如果存在 learnings.consolidated.md，请查阅该文件；仅在需要查看历史记录或将其作为可用的后备方案时，使用 learnings.md。否则跳过这两个文件。

应用经验后，如果遇到了值得记住的模式、值得避免的错误，或令你意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的项目。不要修改 SKILL.md 本身。