为什么需要多版本管理？

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

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

---

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

1. URL路径中包含版本号

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

示例代码：

@RestController
@RequestMapping("/api/v1/products")
public class ProductControllerV1 {

    @GetMapping
    public List<Product> getProductsV1() {
        // 返回 V1 版本的产品列表
        return List.of(new Product("Product1", "Description1"));
    }
}

@RestController
@RequestMapping("/api/v2/products")
public class ProductControllerV2 {

    @GetMapping
    public List<Product> getProductsV2() {
        // 返回 V2 版本的产品列表
        return List.of(new Product("Product1", "New Description"));
    }
}

2. 请求头中包含版本号

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

示例代码：

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @GetMapping
    public 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 {
     
         @Override
         public 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 {
     
         @Override
         public 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路径方式简单直接，适合大多数场景；
• 请求头方式更灵活，适合需要动态版本控制的场景；
• 自定义注解和拦截器方式适用于复杂的版本管理需求。