Spring Boot 4.0 要来了，API版本功能太赞了！

Spring 官方已经发布了 Spring Boot 4.0 的快照版本，内置 Spring Framework 7.0。

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

虽然笔者在此前的文章中已介绍过相关流程，但在实际使用 Spring Boot 4.0 版本时，仍存在一些细微差异，值得进一步说明与优化。

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

基础使用：RequestMapping version 属性

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

@Configuration
publicclassWebConfigurationimplementsWebMvcConfigurer {

    @Override
    publicvoidconfigureApiVersioning(ApiVersionConfigurer configurer) {
        // 方式 1：使用请求参数（默认参数名为 "version"）
        configurer.useRequestParam("version");

        // 方式 2：使用请求头
        // configurer.useRequestHeader("API-Version");

        // 方式 3：使用路径变量
        // configurer.usePathVariable("version");
    }
}

版本解析配置：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 的演进，提升系统的可维护性和用户体验。

来源：https://mp.weixin.qq.com/s/P6PlE4cBzYthWwztlnUv0Q

— 感谢阅读 —

一起交流

分享你的思考，让讨论更进一步。