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

# 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: ; rel="sunset"` 提供迁移说明。 - 兼容策略：保持字段的后向兼容；避免在同一资源中混合不兼容变更；通过版本化 Schema 与契约测试控制演进。 ## 实战清单 - 对破坏性变更采用路径版本；微小演进用媒体类型参数，降低侵入性。 - 在网关层记录版本与调用画像；设定弃用窗口与告警阈值。 - 结合契约测试与灰度发布，保证跨版本行为一致与安全回滚。