Spring Boot API版本控制实战：三种主流方案详解

Spring Boot API版本控制实战：三种主流方案详解

引用

CSDN

1.

https://blog.csdn.net/yangshangwei/article/details/141000898

在现代软件开发中，API版本控制是一个至关重要的概念。它允许开发者在不影响现有用户的情况下引入新功能或做出重大改变。本文将详细介绍在Spring Boot中实现API版本控制的三种主流方案：URL路径中包含版本号、请求头中包含版本号以及自定义注解和拦截器。

为什么需要多版本管理？

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

本文原文来自CSDN