---

title: API版本治理：URI、Header与内容协商

keywords:

• API版本
• URI版本
• Header版本
• 内容协商
• 兼容性

description: 系统化比较路径版本、请求头版本与媒体类型内容协商方案，指导在演进中保持后向兼容与清晰的变更边界。

categories:

• 文章资讯
• 技术教程

---

API版本治理：URI、Header与内容协商

概览

• 版本治理目标：清晰的变更边界、后向兼容与可控弃用节奏。
• 常见策略：路径版本（/v1）、请求头版本（Accept 媒体类型）、内容协商（RFC 9110）。

技术参数（已验证）

• 路径版本：/v{n} 适合破坏性变更；利于网关路由与并存多版本。
• 请求头版本：Accept: application/vnd.acme.v2+json 通过媒体类型参数实现；遵循 HTTP 语义（RFC 9110）。
• 内容协商：服务根据 Accept/Content-Type 协商响应表示；可并存 JSON/Protobuf 等不同表示。
• 弃用治理：可使用标准 Sunset 响应头（RFC 8594）传达弃用时间，并通过 Link: <url>; rel="sunset" 提供迁移说明。
• 兼容策略：保持字段的后向兼容；避免在同一资源中混合不兼容变更；通过版本化 Schema 与契约测试控制演进。

实战清单

• 对破坏性变更采用路径版本；微小演进用媒体类型参数，降低侵入性。
• 在网关层记录版本与调用画像；设定弃用窗口与告警阈值。
• 结合契约测试与灰度发布，保证跨版本行为一致与安全回滚。