在Java框架中为API添加版本控制是确保系统可维护性和向后兼容性的关键实践。以下是基于Spring Boot框架的详细实现方案：
一、核心实现方式注解配置
使用@RequestMapping的version属性（需自定义拦截器支持）
更推荐使用路径参数或自定义Header方案（Spring默认不支持version属性）
主流实现方案
路径版本控制：/api/v1/users
Header版本控制：Accept: application/vnd.company.app-v1+json
自定义参数：/api/users?version=1
二、推荐实现步骤（路径版本控制）1. 项目配置<!-- pom.xml 核轿手心依赖 --><dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> </dependency></dependencies>2. 实体类定义@Entitypublic class Product { @Id @GeneratedValue private Long id; private String name; private BigDecimal price; // getters/setters}3. Repository接口public interface ProductRepository extends JpaRepository<Product, Long> {}4. 版本化控制携扰器实现@RestController@RequestMapping("/api")public class ProductController { @Autowired private ProductRepository repository; // v1版本 - 基础字段 @GetMapping("/v1/products") public List<ProductV1Response> getProductsV1() { return repository.findAll().stream() .map(p -> new ProductV1Response(p.getId(), p.getName())) .collect(Collectors.toList()); } // v2版本 - 增加价格字段 @GetMapping("/v2/products") public List<ProductV2Response> getProductsV2() { return repository.findAll().stream() .map(p -> new ProductV2Response(p.getId(), p.getName(), p.getPrice())) .collect(Collectors.toList()); }}// v1响应DTOrecord ProductV1Response(Long id, String name) {}// v2响应DTOrecord ProductV2Response(Long id, String name, BigDecimal price) {}三、闭隐嫌Header版本控制实现方案1. 自定义版本解析器@Configurationpublic class WebConfig implements WebMvcConfigurer { @Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(new VersioningInterceptor()); }}public class VersioningInterceptor implements HandlerInterceptor { @Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { String version = extractVersion(request.getHeader("Accept")); request.setAttribute("api.version", version != null ? version : "1"); return true; } private String extractVersion(String acceptHeader) { // 解析类似 "application/vnd.company.app-v1+json" 的Header if (acceptHeader != null && acceptHeader.contains("vnd.company.app-v")) { return acceptHeader.split("app-v")[1].split("+")[0]; } return null; }}2. 控制器适配@GetMapping("/products")public ResponseEntity<?> getProducts(HttpServletRequest request) { String version = (String) request.getAttribute("api.version"); if ("2".equals(version)) { return ResponseEntity.ok(repository.findAll().stream() .map(p -> new ProductV2Response(p.getId(), p.getName(), p.getPrice())) .collect(Collectors.toList())); } // 默认v1处理 return ResponseEntity.ok(repository.findAll().stream() .map(p -> new ProductV1Response(p.getId(), p.getName())) .collect(Collectors.toList()));}四、最佳实践建议版本策略选择
初期开发可使用v1, v2等简单路径版本
成熟后建议改用发布日期版本（如v20231101）
兼容性处理
@GetMapping("/products")public ResponseEntity<?> getProducts( @RequestHeader(value = "X-API-VERSION", defaultValue = "1") int version) { // 版本处理逻辑}文档规范
在Swagger/OpenAPI中明确标注各版本差异
提供版本迁移指南
弃用策略
通过Header返回Warning头通知客户端版本即将弃用
至少维护两个主要版本（当前版+前一版）
五、完整示例项目结构src/main/java/com/example/demo/├── config/│ └── WebConfig.java├── controller/│ └── ProductController.java├── dto/│ ├── ProductV1Response.java│ └── ProductV2Response.java├── model/│ └── Product.java└── repository/ └── ProductRepository.java这种实现方式通过清晰的版本隔离和兼容性处理，能够有效管理API演化过程，同时保持客户端调用的明确性。建议结合Spring Boot Actuator的/actuator/info端点暴露当前支持的API版本信息。
