| 路径版本 | 直观易调试，缺点是版本散落各路径 |
|---|---|
| 头/媒体类型版本 | URL 稳定，调试与缓存配置更复杂 |
| 兼容优先 | 加字段与可忽略枚举值为兼容变更；删改语义才是破坏性变更 |
变更类型与兼容性
| 变更 | 兼容性 | 做法 |
|---|---|---|
| 新增可选字段 | 兼容 | 客户端忽略未知字段 |
| 新增枚举值 | 视客户端实现 | 文档声明需容忍未知值 |
| 字段含义变更 | 破坏 | 新版本或新增字段名替代 |
| 删除字段或收窄校验 | 破坏 | 先观测调用方用量再灰度下线 |
版本数量要控制：每个旧版本都需要维护窗口与下线日期，给消费者留出迁移时间。
API 版本化
对外接口需要可演进的兼容策略：路径版本（/v1）、请求头版本或媒体类型版本各有取舍；优先做兼容性扩展，破坏性变更才升版本。
易错点
- 没有兼容策略，客户端解析新增字段即报错
- 旧版本长期并行维护，修复需要同步多个版本
数据来源与参考
- Google API 设计指南：Versioning
- Microsoft REST API Guidelines