API 版本控制

破坏性变更——例如字段重命名、端点移除或错误信息格式改变——会导致所有基于旧行为构建的客户端都无法正常工作。版本控制允许提供商在旧行为继续运行的同时，将新行为作为新版本发布，并给予客户端一定的迁移时间。

工作原理

版本信息通常包含在 URL 路径中（ /v1 /、 /v2 /），有时也会出现在响应头或 Accept 媒体类型中，偶尔也会以日期形式出现。非破坏性变更（例如新增可选字段、新增端点）会在同一版本内发布。当旧版本停用时，服务提供商会提前发布公告，通常会在响应头中包含 Deprecation 和 Sunset 信息。

误解

添加字段并非总是安全的。只有那些忽略未知字段的客户端才会遇到问题，而那些使用严格反序列化器或快照测试的客户端则会受到影响。至于什么才算"breaking"则取决于客户端的实际操作，因此服务提供商会公布其兼容性规则。

点击这里试试

Friends API 运行两个版本：GET /friends/v1/characters已标记为已弃用，GET /friends/v2/characters将 job 重命名为 occupation 并重新包装列表；GET /friends/version列出了支持的内容。

相关内容

• 弃用和终止标头
• Friends API docs

资料来源

• HTTP semantics — RFC 9110
• OpenAPI Initiative

其他术语

• 弃用和终止标头 — 响应头会警告客户端某个端点即将关闭，以及何时停止工作。

阅读英文版

所有术语 · 测试技巧 · 全部 39 个模拟 REST API

最后更新时间 2026年10月16日