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

文章目录

为什么需要多版本管理？
[在Spring Boot中实现多版本API的常用方法](#在Spring Boot中实现多版本API的常用方法)
- [1. URL路径中包含版本号](#1. URL路径中包含版本号)
- [2. 请求头中包含版本号](#2. 请求头中包含版本号)
- [3. 自定义注解和拦截器](#3. 自定义注解和拦截器)
注意事项

为什么需要多版本管理？

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

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

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

1. URL路径中包含版本号

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

示例代码：

java 复制代码

@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. 请求头中包含版本号

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

示例代码：

java 复制代码

@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版本，并使用拦截器进行版本控制。

步骤：

创建自定义注解 ：

java 复制代码

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

创建版本拦截器 ：

java 复制代码

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;
    }
}

配置拦截器 ：

java 复制代码

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new ApiVersionInterceptor());
    }
}

在控制器中使用注解：

java 复制代码

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