api-design-and-evolution

API 设计与演进

将接口设计成与使用者之间持久有效的约定，而非路由列表。 先明确使用者要完成的任务、领域含义、权限边界和故障模式； 然后再选择接口风格和契约格式。区分事实、假设和策略决策。

适用场景

用于新的或变更后的 REST/HTTP API、GraphQL 架构、RPC 操作、事件或 消息契约、Webhook 或流式接口。在实现前使用，并在使用者可见的行为发生变更时 再次使用。

不适用场景

不要将其用作 ADR 模板、完整的产品探索方法、安全评估或实现测试计划。分别将这些事项交由 adr-authoring、 product-discovery、 secure-software-engineering 和 verification-methodology 处理。

工作流

1. 确定范围。 如果请求涉及多个接口，请从 templates/api-landscape-assessment.md 开始， 并阅读 references/api-landscape-and-governance.md。 如果请求会改变流量的准入、路由、观测或隔离方式，请阅读 references/api-infrastructure-topologies.md。 将产品组合层面的发现与任何单个契约决策分开记录。
2. 梳理共识。 说明消费者的任务、领域术语和不变量、 权威数据与架构的所有者、参与者、对象／操作的权限边界、 数据敏感度和故障模式。记录尚未解答的问题，不要自行臆定策略。开始填写 templates/api-design-brief.md。 当 Agent 或自动化是直接消费者时，还要阅读 references/agent-consumer-interfaces.md， 并完成 templates/agent-consumer-interface-review.md。
3. 选择接口形态。 比较交互方向、耦合程度、 交付需求、查询灵活性、变更语义、缓存、可观测性和演进范围。阅读 references/interface-selection.md。 在设计简报中记录所选方案和被否决的选项；仅当该选择的影响超出此接口时，才使用 ADR。
4. 明确契约。 定义表示形式及其语义， 包括 null 与缺失的区别、默认值、枚举／联合类型、标识符、时间戳、 单位、排序、筛选和分页。使用 templates/endpoint-contract.md 和 references/contract-semantics.md。
5. 设计变更与故障行为。 定义权限检查、前置条件、 幂等范围与等价性、重试、并发、部分结果、 长时间运行操作的状态、错误和资源限制。阅读 references/operations-and-failures.md， 并在多个操作共享错误时创建 templates/error-taxonomy.md。
6. 在相关情况下说明异步交付。 对于消息、Webhook 或 流，说明发布者／订阅者视角、信封、交付契约、 重复／缺口／乱序行为、排序范围和安全边界。阅读 references/events-webhooks-streaming.md。
7. 从每个消费者的角度评估变更。 列出消费者、 生成的客户端、严格解码器、签名、缓存、配额和运维依赖项。完成 templates/compatibility-change-assessment.md。 不要仅因变更是增量式的，就认定它安全。
8. 规划并验证发布。 对于弃用或迁移，请使用 templates/deprecation-migration-plan.md 和 references/evolution-and-deprecation.md。 使用 templates/contract-review.md 审查契约。 测试提供方的一致性、消费者预期、兼容性差异、示例、 负面案例和已部署边界。兼容性策略定义后，加载 release-engineering，以处理发布顺序、 制品晋级、渐进式开放和协调回滚。

参考指南

加载时机	文件
评估 API 组合、所有权、重复、可发现性、生命周期、标准或弃用时	references/api-landscape-and-governance.md 和 templates/api-landscape-assessment.md
比较网关、入口代理、服务网格、流量方向、路由、策略、遥测或故障边界时	references/api-infrastructure-topologies.md
选择 REST/HTTP、GraphQL、RPC、事件/消息、Webhook 或流式传输时	references/interface-selection.md
建模数据、集合读取、架构或 OpenAPI 时	references/contract-semantics.md
设计写入、错误、重试行为、限制或授权交接时	references/operations-and-failures.md
设计事件契约、Webhook 交付或流时	references/events-webhooks-streaming.md
审查兼容性、版本、弃用、迁移或回滚时	references/evolution-and-deprecation.md
准备契约/提供方/使用方/部署验证时	references/contract-verification.md
核实准确来源、版本、状态和预期用途时	references/source-index.md
审查 Agent 和自动化直接使用的 API 或工具时	references/agent-consumer-interfaces.md 和 templates/agent-consumer-interface-review.md
在宣称已就绪前验证必需的边界情况时	references/scenario-probes.md

安全边界

在接口契约中记录身份验证要求，以及服务端对象/操作授权。对于威胁模型、凭据处理、租户隔离、不可信 URL 或文件、Webhook 签名设计、输出最小化、脱敏或滥用防护，请参阅 secure-software-engineering。API 契约无法证明授权边界已得到强制执行。

所有权边界

• 产品负责人决定使用方结果、受众、价值和生命周期意图；此技能将这些决策转化为接口约定和证据。
• 平台负责人决定网关、入口、服务网格、网络、部署和运行时运维。此技能明确拓扑职责和契约影响，但不负责运营底层平台。
• 安全负责人决定威胁模型、凭据和机密控制、滥用防护及租户隔离。此技能记录契约交接和所需授权行为，但不能替代安全评估。
• 架构负责人决定跨系统原则、重要边界和持久的架构决策。当 API 组合或拓扑决策的影响超出 API 范围时，请使用 adr-authoring。

API 组合评估不是产品路线图、平台运维手册、安全审查或企业架构资料库。对于尚未解决的所有权、决策权限或弃用决策，应予以升级处理，而不要擅自归属。

完成条件

当选定的接口有明确负责人和权威契约、明确的使用方及故障假设、针对每项变更的兼容性评估，并且每项必需审查都有证据或明确记录的缺口时，即可停止。将尚未解决的领域语义、决策权限、交付或使用方影响问题升级给相应负责人。