Spring 官方已经发布了 Spring Boot 4.0 的快照版本,内置 Spring Framework 7.0。
Spring Framework 7.0 引入了对 API 版本控制的原生支持,为服务器端和客户端应用程序提供了强大的工具,以高效处理版本特定的路由和请求。
虽然笔者在此前的文章中已介绍过相关流程,但在实际使用 Spring Boot 4.0 版本时,仍存在一些细微差异,值得进一步说明与优化。
基础使用: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");
}
}
常见的版本控制策略
?version=1
API-Version: 1
/api/v1/users
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";
}
});
}
}
总结
通过 Spring Boot 4.0 的原生版本控制支持,开发者可以更优雅地管理 API 的演进,提升系统的可维护性和用户体验。
来源:https://mp.weixin.qq.com/s/P6PlE4cBzYthWwztlnUv0Q
没有回复内容