标准答案
- URL 版本如 /v2/orders 最直观，便于路由、文档、监控和客户端切换，但会让资源地址随版本增加。
- Header 版本或媒体类型版本能保持 URL 稳定，适合协议协商，但调试、缓存键和人工调用时需要更严格的工具与约定。
- 新增可选响应字段、增加新端点、放宽输入范围通常可以保持兼容；删除字段、改变字段类型或含义、收紧校验和改变默认行为通常是破坏性变化。
- 升级前要明确旧版支持期限、调用量、迁移 SDK、兼容层和下线条件；版本不是只在路由中加一个数字。
- 无论版本放在哪里，错误码、认证、幂等、分页和可观测性都应维持一致的基础约定。
题目解析
频繁大版本往往说明初始契约不稳定或扩展方式不足。优先通过容忍未知字段、明确默认值和新的能力字段演进。
版本路由还影响网关、缓存、SDK、文档和指标维度；选择后要让这些环节都能识别版本。
常见误区
- 每增加一个字段就发布新版本，造成客户端碎片化。
- 认为 URL 版本一定落后于 Header 版本，或反过来。
- 发布 v2 后没有旧版迁移计划和下线观测。