微服务架构中，API 版本控制是保障服务演进过程中兼容性和稳定性的关键手段。随着业务迭代，接口可能新增字段、修改参数或调整返回结构，若不进行版本管理，容易导致客户端调用失败。实现 API 版本控制的核心思路是在请求中明确标识所使用的 API 版本，服务端据此提供对应的行为。
1. URL 路径中包含版本号
这是最常见且直观的方式，将版本信息直接嵌入 API 的 URL 路径中。
示例：- v1 用户信息接口：/api/v1/users/123
- v2 接口：/api/v2/users/123
服务端通过路由匹配不同版本的控制器或处理逻辑。这种方式易于理解、调试和部署，适合大多数场景。缺点是 URL 变得冗长，且在重构时路径变更可能影响网关或文档管理。
2. 请求头中传递版本信息
将版本信息放在 HTTP 请求头中，保持 URL 的简洁性。
示例：Accept: application/vnd.myapp.v1+json
或自定义头：X-API-Version: v2
服务端根据请求头内容路由到对应版本的处理逻辑。这种方式对前端更透明，URL 不变，适合对外提供统一入口的开放平台。但调试不便，需借助工具查看请求头，且容易被忽略或误配。
3. 查询参数指定版本
通过 URL 查询参数传递版本号，实现简单但不够规范。
示例：/api/users/123?version=v1
优点是改动小，适合内部系统快速迭代。缺点是缓存策略复杂，GET 外的请求也不够优雅，一般不推荐用于正式生产环境。
4. 服务端版本路由与兼容性处理
无论采用哪种方式，服务端都应做到：
不同版本的逻辑隔离，可独立维护 旧版本逐步标记为废弃（Deprecate），并提供迁移指引 利用中间件或拦截器统一解析版本信息 结合 API 网关统一管理版本路由，减轻微服务负担同时，建议配合 OpenAPI（Swagger）为每个版本生成独立文档，便于前后端协作。
基本上就这些。选择哪种方式取决于团队习惯和系统规模，URL 路径方式最常用，请求头方式更适合精细化控制。关键是建立清晰的版本策略，避免混乱。
