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 的演进，提升系统的可维护性和用户体验。
