Spring Boot REST接口版本控制核心是共存、路由与隔离，主流方式有三种：1. URL路径版（如/api/v1/users），直观易调试，通过@RequestMapping前缀区分；2. 请求头版（如X-API-Version: v2），需自定义RequestCondition和HandlerMapping，保持URL干净；3. Media Type版（如Accept: application/vnd.myapp.v2+json），基于produces内容协商，语义规范但客户端要求高。
Spring Boot 实现 REST 接口版本控制，核心是让不同版本的逻辑能共存、可路由、不干扰。URL 路径版最直观，Header 版更灵活，两者适用场景不同，实现方式也各有侧重。
URL 路径版本控制（/api/v1/users）
把版本号直接写进请求路径，是最常用、最易调试的方式。Spring Boot 通过 @RequestMapping 的路径前缀区分版本，每个版本对应独立的 Controller 类或包。
- 每个版本一个 Controller，用不同路径映射，比如：
@RestController @RequestMapping("/api/v1/users") public class UserControllerV1 { ... }
@RestController @RequestMapping("/api/v2/users") public class UserControllerV2 { ... } - 路径清晰，前端调用时一目了然，日志和网关路由也容易识别版本
- 注意避免重复代码：可提取公共 Service 层，V1/V2 Controller 只负责 DTO 转换与协议适配
- 不建议用
@RequestMapping("/api/{version}/users")+ 参数校验来统一路由——这会失去编译期约束，也难以做版本生命周期管理
请求头版本控制（X-API-Version: v2）
把版本信息放在请求头里，保持 URL 干净，适合客户端可控、且希望接口形态长期稳定的场景。Spring Boot 默认不支持，需自定义 RequestCondition 和 HandlerMapping。
Alibabacloud Sdk Client Initialization For Java
下载
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
- 定义一个注解，如
@ApiVersion("v2")，标注在 Controller 或方法上 - 实现
RequestCondition<ApiVersionCondition>，从request.getHeaders().getFirst("X-API-Version")提取并匹配版本 - 继承
RequestMappingHandlerMapping，重写getCustomTypeCondition()，注册你的条件类 - 最终效果是：
@RestController
public class UserController {
@GetMapping("/users")
@ApiVersion("v1")
public List<UserV1> listV1() { ... }
@GetMapping("/users")
@ApiVersion("v2")
public List<UserV2> listV2() { ... }
}
Media Type 版本控制（Accept: application/vnd.myapp.v2+json）
属于内容协商范畴，利用标准 HTTP 的 Accept 头声明期望的媒体类型和版本。它语义更规范，但对客户端要求更高，调试不如前两种直接。
- Spring MVC 原生支持基于
produces的媒体类型路由，例如：
@GetMapping(value = "/users", produces = "application/vnd.myapp.v1+json")
public ResponseEntity<List<UserV1>> listV1() { ... }
@GetMapping(value = "/users", produces = "application/vnd.myapp.v2+json")
public ResponseEntity<List<UserV2>> listV2() { ... } - 需确保客户端正确设置
Accept头，服务端也要配置好消息转换器（如 Jackson 对应的ObjectMapper注册） - 适合对外提供标准化 OpenAPI 的场景，比如 SaaS 平台 API
怎么选？看实际约束
没有绝对优劣，关键看团队协作习惯和客户端能力：
- 内部系统、快速迭代、前端强配合 → 优先用 URL 路径版，省心可靠
- 对外 SDK、多语言客户端、已有统一网关 → Header 版本更利于统一治理
- 已有成熟内容协商机制、或对标行业规范（如 GitHub API）→ Media Type 更合规
- 避免混合使用：同一套 API 不要同时开放 /v1/xxx 和 X-API-Version，否则路由歧义、维护成本陡增
