为什么需要版本管理
API一旦发布就有外部客户端依赖。任何破坏性变更（Breaking Change）都可能导致客户端崩溃。版本管理让新旧API并行运行，给客户端足够的迁移时间。
版本管理策略
URL路径版本
最直观的方式：/api/v1/users、/api/v2/users。优点：清晰明了、缓存友好、调试方便。缺点：URL污染、老版本代码需要持续维护。GitHub、Twitter、Stripe均使用此方案。
Header版本
通过Accept Header指定版本：Accept: application/vnd.api+json;version=2。优点：URL保持干净。缺点：浏览器直接访问不方便、CDN缓存配置复杂。
Query参数版本
通过参数指定：/api/users?version=2。不推荐用于正式API，适合内部测试。
无版本策略（演进式API）
通过只做向后兼容的变更避免版本号。新增字段不影响旧客户端，废弃字段标记deprecated但不删除。GraphQL天然适合此策略。
Breaking Change识别
- 删除或重命名字段 → Breaking
- 更改字段类型 → Breaking
- 新增必填参数 → Breaking
- 新增可选字段 → Non-breaking
- 新增端点 → Non-breaking
迁移最佳实践
发布新版本 → 通知客户端（邮件/文档/changelog）→ 设置旧版本日落时间（至少6个月）→ 监控旧版本使用量 → 逐步引导迁移 → 旧版本返回Sunset Header和deprecation警告 → 最终下线。
文档管理
每个版本维护独立的API文档（OpenAPI规范）。使用Redoc或Swagger UI自动生成在线文档。文档中明确标注deprecated字段和迁移指南。