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 属性，让版本控制变得更加简洁和直观。

@RequestMapping
@RestController
publicclassDemoController {

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

    @GetMapping(version = "2")
    public String version2() {
        return"API Version 2.0.0";
    }
}

版本解析配置：ApiVersionConfigurer

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

@Configuration
publicclassWebConfigurationimplementsWebMvcConfigurer {

    @Override
    publicvoidconfigureApiVersioning(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 的 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/"

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

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

@Configuration
publicclassWebConfigurationimplementsWebMvcConfigurer {

    @Override
    publicvoidconfigureApiVersioning(ApiVersionConfigurer configurer) {
        configurer.useVersionResolver(newApiVersionResolver() {
            @Override
            public@Nullable String resolveVersion(HttpServletRequest request) {
                // 示例 1：从用户代理字符串解析版本
                StringuserAgent= request.getHeader("User-Agent");
                if (userAgent != null && userAgent.contains("mobile")) {
                    return"mobile";
                }

                // 示例 2：基于客户端 IP 或其他业务规则
                StringclientIp= getClientIp(request);
                if (isTestEnvironment(clientIp)) {
                    return"beta";
                }

                // 默认版本
                return"1";
            }
        });
    }
}

总结

• 1.用户发起请求，进入 RequestMappingHandlerMapping，用于确定应该调用哪个 Controller 方法。

• 2.RequestMappingHandlerMapping 调用 ApiVersionStrategy，提取请求中的 API 版本号。

• 3.返回 API 版本号后，进行初步筛选符合条件的 Controller 方法。

• 4.选择出最佳匹配的 Controller 方法。

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