java rest接口版本控制有三种主流策略：1. url路径嵌入版本号（如/api/v1/users），直观易调试但路径冗长；2. 请求头传递（如x-api-version），路径干净但调试不便；3. accept头配合自定义媒体类型，最符合rest理念但实现复杂。
Java 中 REST 接口的版本控制，核心是让新旧功能共存、不破坏已有调用方。没有“唯一正确”的方式，但有三种主流策略可直接落地，各自适用不同场景。
URL 路径中嵌入版本号
最常用、最直观的方式：把 v1、v2 直接写进请求路径里。
- 例如：
/api/v1/users/123和/api/v2/users/123分别对应两个版本的用户查询接口 - Spring Boot 中只需在
@RequestMapping或@GetMapping的 value 中体现，比如@GetMapping("/api/v1/users/{id}") - 优点是调试方便、CDN 和网关能天然识别、客户端容易理解
- 缺点是 URL 变得冗长，升级时客户端必须改路径；长期维护多个版本可能导致路径分支过多
通过请求头传递版本信息
保持 URL 干净，把版本交给 HTTP 头管理，比如自定义 X-API-Version。
- 客户端发起请求时带上：
X-API-Version: v2 - 服务端用 Spring 的
headers = "X-API-Version=v2"做方法映射，如：@GetMapping(value = "/users/{id}", headers = "X-API-Version=v2") - 好处是资源路径不变，语义更纯粹，适合内部系统或 SDK 封装场景
- 缺点是浏览器地址栏无法直接测试，排查问题需额外检查请求头，对前端或第三方调用方不够友好
用 Accept 头配合自定义媒体类型
基于 HTTP 内容协商机制，把版本信息藏在 Accept 请求头的 MIME 类型中。
- 客户端请求头设为：
Accept: application/vnd.myapp.users-v2+json - 服务端用
produces属性匹配：@GetMapping(value = "/users/{id}", produces = "application/vnd.myapp.users-v2+json") - 这是最符合 REST 理念的方式，完全解耦版本与路径，也利于未来支持 XML、Protobuf 等多种格式
- 但实现稍复杂，需要注册自定义 MediaType，学习和维护成本略高，中小型项目较少采用
实际选型建议：新项目起步优先用 URL 路径方式，清晰可控；团队成熟、客户端统一且重视协议规范，可考虑 Accept 头方案；请求头方式适合已有路径不便改动、又想快速引入版本隔离的过渡场景。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
