资源 · 33
在不流失客户端的情况下改进 API 合约。
描述请求、响应和错误；测试版本并确保 Webhook 可安全重放。
已更新 · 2 min
本指南有助于实现的目标
- 编写合同
- 澄清错误
- 测试兼容性
- 规划停用
快速检查
- 哪些客户端使用每个操作？
- 错误类型是否稳定且状态一致？
- 旧客户端能否容忍此变更？
- 重试是否会重复操作？
- 如何宣布和验证停用？
分步指南
- 1
清点使用者
列出操作、客户端、使用情况、版本和所有者。 在更改字段之前，将观察到的使用情况与假设区分开来。
交付成果：合同依赖关系图。
- 2
描述请求和响应
维护包含模式、实际示例、成功和失败响应的 OpenAPI 描述。 针对正在运行的服务进行检查。
交付成果：版本化的契约和一致性测试。
- 3
稳定错误
根据语义使用 HTTP 状态，并在必要时使用 RFC 9457 中记录的问题类型。不要泄露敏感信息的细节。
交付成果：已测试的错误目录。
- 4
对变更进行分类
检查必填字段、类型、值、行为、超时和分页。 使用代表性案例测试旧客户端与新版本的兼容性。
交付成果：兼容性矩阵和版本决策。
- 5
增强通知的健壮性
对于 Webhook，规划身份验证、无序传递、重复和重试机制。 在可能重复的情况下，确保处理过程的幂等性。
交付成果：重放和确认场景。
- 6
发布版本，并提供退出路径
发布迁移说明、共存期和联系方式。 统计旧版本使用情况，并在确认受影响用户后方可停用。
交付成果：迁移计划和停用证明。
管理指标
| 指标 | 衡量内容 | 首要行动 |
|---|---|---|
| 合同 | 操作描述及与服务行为的匹配 | 修复差异 |
| 兼容性 | 变更前对代表性客户端进行测试 | 添加缺失案例 |
| 错误 | 记录不包含敏感数据的类型 | 修改消息和模式 |
| 迁移 | 允许使用旧版本并指定所有者 | 协助剩余客户端 |
常见错误
- 假设仅版本号即可保持兼容性
- 仅记录 200 个响应
- 在错误中返回内部跟踪或密钥
- 假设 Webhook 仅按顺序到达一次
常见问题解答
OpenAPI 是否取代测试？
否。将描述与实际响应和用户需求进行比较。
每次变更都需要新版本吗？
否。根据客户端影响和合同行为来决定； 不兼容的变更需要明确的计划。
为什么需要输入错误？
它们为客户提供了一种稳定的方式来区分问题并选择相应的操作。
官方参考文献
参考文献支持该方法。 请根据您的实际情况调整检查；它们并非认证。 原始参考文献标题和源文档可能使用其他语言。
