Spring Boot 4.0来了！API版本控制竟然这么香

(Updated: )
Java

3WDCYP

Spring 官方已经发布了 Spring Boot 4.0 的快照版本，内置 Spring Framework 7.0。Spring Framework 7.0 引入了对 API 版本控制的原生支持，为服务器端和客户端应用程序提供了强大的工具，以高效处理版本特定的路由和请求。

API 版本控制是现代 Web 开发中的关键实践，它允许开发者在不破坏现有客户端的情况下管理 API 的演进和变更，确保向后兼容性的同时引入新功能。

基础使用：RequestMapping version 属性

Spring Framework 7.0 在 @RequestMapping 及其变体注解中新增了 version 属性，让版本控制变得更加简洁和直观。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
@RequestMapping
@RestController
public class DemoController {

    @GetMapping(version = "1")
    public String version1() {
        return "API Version 1.0.0";
    }

    @GetMapping(version = "2")
    public String version2() {
        return "API Version 2.0.0";
    }
    
    // 支持多版本
    @GetMapping(version = {"1", "2"})
    public String commonEndpoint() {
        return "支持多个版本的通用端点";
    }
}

EWwINT

版本解析配置：ApiVersionConfigurer

通过实现 WebMvcConfigurer 接口并重写 configureApiVersioning 方法，可以自定义版本解析策略。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@Configuration
public class WebConfiguration implements WebMvcConfigurer {

    @Override
    public void configureApiVersioning(ApiVersionConfigurer configurer) {
        // 方式1：使用请求参数（默认参数名为 "version"）
        configurer.useRequestParam("version");
        
        // 方式2：使用请求头
        // configurer.useRequestHeader("API-Version");
        
        // 方式3：使用路径变量
        // configurer.usePathVariable("version");
    }
}

常见的版本控制策略

  1. 请求参数方式：?version=1
  2. 请求头方式：API-Version: 1
  3. 路径变量方式：/api/v1/users
  4. Accept 头方式：Accept: application/vnd.api+json;version=1

调用测试

使用请求参数进行版本控制的测试示例：

1
2
3
4
5
6
7
8
9
10
# 调用版本1的API
curl "http://localhost:8080/?version=1"
# 输出：API Version 1.0.0

# 调用版本2的API  
curl "http://localhost:8080/?version=2"
# 输出：API Version 2.0.0

# 不指定版本（可能返回默认版本或错误）
curl "http://localhost:8080/"

高级配置：自定义版本解析器

对于复杂的业务场景，可以实现自定义的版本解析逻辑：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
@Configuration
public class WebConfiguration implements WebMvcConfigurer {

    @Override
    public void configureApiVersioning(ApiVersionConfigurer configurer) {
        configurer.useVersionResolver(new ApiVersionResolver() {
            @Override
            public @Nullable String resolveVersion(HttpServletRequest request) {
                // 示例1：从用户代理字符串解析版本
                String userAgent = request.getHeader("User-Agent");
                if (userAgent != null && userAgent.contains("mobile")) {
                    return "mobile";
                }
                
                // 示例2：基于客户端IP或其他业务规则
                String clientIp = getClientIp(request);
                if (isTestEnvironment(clientIp)) {
                    return "beta";
                }
                
                // 默认版本
                return "1";
            }
        });
    }
}

总结

yrCsJB

通过 Spring Boot 4.0 的原生版本控制支持，开发者可以更优雅地管理API的演进，提升系统的可维护性和用户体验。