SuperAPI AI 工具集

api-contract-evolution

编程与开发

查看项目

更新于 10-16 08:02

技能介绍

用途:在不破坏无法强制升级的客户端(移动应用、第三方集成)的前提下,随时间演进 REST API。design-api 关注编写新端点,本技能关注如何修改已有端点。

版本策略(择一):URL 路径(/v1/、/v2/)适合公开 API 与移动客户端,可见、可缓存、易测试,为首选;请求头(API-Version: 2024-01-01)适合调用方均可控的内部服务间调用;查询参数(?version=2)应避免,会破坏缓存且易遗漏;GraphQL 则通过新增字段、@deprecated 演进,确认零使用后再移除。

破坏性与非破坏性变更:非破坏性(无需升版本)包括新增带合理默认值的可选请求字段、新增响应字段(需测试客户端确实忽略未知字段)、放宽校验、新增端点或枚举值。破坏性(需新版本或弃用窗口)包括删除、重命名、改变字段类型或语义、收紧校验、改变响应结构或 HTTP 方法语义、移除端点。

弃用生命周期:添加 Deprecation: true 与 Sunset: <RFC 7231 日期> 响应头;按客户端(API key、user agent、IP)记录使用量;在日落前带使用证据通知消费者;日落后返回 410 Gone,并保留路由以给出明确错误;监控流量归零后再移除代码。最短窗口:外部 API 3 个月,移动端 6 个月(应用商店周期会延迟采用)。

OpenAPI 作为契约来源:每个版本一份 OpenAPI 规范,据此生成文档、SDK 与 mock;CI 中用 oasdiff 或 openapi-diff 检测破坏性变更,未升版本的破坏性变更应使构建失败;消费者驱动契约测试(Pact)由消费者发布 pact,提供方 CI 在每次变更时验证。

SDK 生成:用 openapi-generator、fern 或 speakeasy 生成带类型的 SDK,客户端固定 SDK 版本而非裸 HTTP;未经迁移指南不得自动发布 SDK 主版本。

向后兼容测试:从生产录制黄金请求/响应对,在 CI 中对新版本回放,断言响应符合旧客户端期望的 schema。工具:VCR(Ruby)、pytest-recording(Python)、Polly.js、MSW record mode。

护栏:不改变字段含义而不改名(语义漂移对类型检查器不可见);未先跟踪真实使用量不得弃用;日落日期不得短于最长发布周期;不得在无测试确认的情况下假定客户端忽略未知字段。