Spring Boot - 在Spring Boot中实现灵活的API版本控制（上）

为什么需要多版本管理？

API接口的多版本管理在我们日常的开发中很重要，特别是当API需要在不影响现有用户的情况下引入新功能或做出重大改变时。

1. 满足不同需求：不同客户可能有不同需求。通过多版本管理，可以同时支持多个版本，满足不同用户的特定需求。
2. 风险控制：允许开发团队逐步迁移到新版本，而不是强制所有用户一次性切换，减少大规模迁移的风险。
3. 新功能引入：在不影响旧版本稳定性的前提下，通过新版本引入新功能和改进。
4. 独立维护：不同版本的API可以独立进行错误修复和安全更新。

---

在Spring Boot中实现多版本API的常用方法

1. URL路径中包含版本号

实现方式：在URL路径中添加版本号。

示例代码：

@RestController
@RequestMapping("/api/v1/products")
public class ProductControllerV1 {@GetMappingpublic List<Product> getProductsV1() {// 返回 V1 版本的产品列表return List.of(new Product("Product1", "Description1"));}
}@RestController
@RequestMapping("/api/v2/products")
public class ProductControllerV2 {@GetMappingpublic List<Product> getProductsV2() {// 返回 V2 版本的产品列表return List.of(new Product("Product1", "New Description"));}
}

2. 请求头中包含版本号

实现方式：通过请求头传递版本信息，控制器根据版本号处理请求。

示例代码：

@RestController
@RequestMapping("/api/products")
public class ProductController {@GetMappingpublic List<Product> getProducts(@RequestHeader(value = "API-VERSION", defaultValue = "1") String apiVersion) {if ("1".equals(apiVersion)) {return getProductsV1();} else if ("2".equals(apiVersion)) {return getProductsV2();}return getProductsV1(); // 默认返回 V1 版本}private List<Product> getProductsV1() {// 返回 V1 版本的产品列表return List.of(new Product("Product1", "Description1"));}private List<Product> getProductsV2() {// 返回 V2 版本的产品列表return List.of(new Product("Product1", "New Description"));}
}

3. 自定义注解和拦截器

实现方式：通过自定义注解标记API版本，并使用拦截器进行版本控制。

• 步骤：
  1. 创建自定义注解：

     @Target(ElementType.METHOD)
     @Retention(RetentionPolicy.RUNTIME)
     public @interface ApiVersion {int value();
     }
     

  2. 创建版本拦截器：

     public class ApiVersionInterceptor implements HandlerInterceptor {@Overridepublic boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {if (handler instanceof HandlerMethod) {HandlerMethod handlerMethod = (HandlerMethod) handler;ApiVersion apiVersion = handlerMethod.getMethodAnnotation(ApiVersion.class);if (apiVersion != null) {String version = request.getHeader("API-VERSION");if (version != null && Integer.parseInt(version) != apiVersion.value()) {response.sendError(HttpServletResponse.SC_BAD_REQUEST, "API version mismatch");return false;}}}return true;}
     }
     

  3. 配置拦截器：

     @Configuration
     public class WebConfig implements WebMvcConfigurer {@Overridepublic void addInterceptors(InterceptorRegistry registry) {registry.addInterceptor(new ApiVersionInterceptor());}
     }
     

  4. 在控制器中使用注解：

@RestController
@RequestMapping("/api/products")
public class ProductController {@GetMapping@ApiVersion(1)public List<Product> getProductsV1() {// 返回 V1 版本的产品列表return List.of(new Product("Product1", "Description1"));}@GetMapping@ApiVersion(2)public List<Product> getProductsV2() {// 返回 V2 版本的产品列表return List.of(new Product("Product1", "New Description"));}
}

注意事项

• 在使用自定义注解和拦截器时，确保拦截器的执行顺序正确，以避免影响其他拦截器的功能。
• URL路径方式简单直接，适合大多数场景；
• 请求头方式更灵活，适合需要动态版本控制的场景；
• 自定义注解和拦截器方式适用于复杂的版本管理需求。