Spring Boot4正式篇：第二篇 多版本API特性

日期	更新说明
2025年11月21日	初版完成
2025年11月22日	源码解析部分

前言

今天 2025年11月21日 是Spring Boot4发布正式版本的日子，也是开始正式更新Spring Boot4系列正式篇的开始。

在以SpringBoot开发Restful接口时，由于模块，系统等业务的变化，需要对同一接口 提供不同版本的参数实现（老的接口还有模块或者系统在用，不能直接改，所以需要不同版本）。如何更加优雅的实现多版本接口呢？在Spring Boot4新版本中默认支持多版本API特性。

开始

示例代码代码地址：github.com/will-we/blo...

后续的代码都会持续更新，多 fork，多关注哈。

配置多版本 API

通过WebMvcConfigurer开启多版本配置，具体代码如下：

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    // 配置版本策略
    @Override
    public void configureApiVersioning(ApiVersionConfigurer configurer) {
        configurer.setVersionRequired(false)
                .useQueryParam("version");
    }
}

Spring 内置几种多类型的多版本参数配置；当然也可以自定义ApiVersionResolver来自行决定多版本解析逻辑：

• 请求头（Request header）
• 请求参数（Request parameter）
• 路径段（Path segment）
• 类型参数（Media type parameter）

请记一下上面的英文单词，下面具体配置多版本的 API

接口多版本标注

@RestController
public class HelloWorldVersionController {

    @RequestMapping(path = "hello", version = "v1")
    public String hello_v1() {
        return "hello world:v1";
    }

    @RequestMapping(path = "hello",version="v2")
    public String hello_v2() {
        return "hello world:v2";
    }
}

验证配置多版本特性

这里可以看到，我们通过version参数控制了 API 的控制逻辑

源码解读

Spring Boot4 是如何实现多版本控制的逻辑呢？我们探究下 Spring Boot4 源码的源码实现吧

1. 回忆下 Spring MVC 处理 Reqeust 的流程吧

这个是一个经典的八股文面试题啦

请求过程

2. 重点关注RequestMappingHandlerMapping#getHandler开始解读，

3. RequestMappingHandlerMapping#initApiVersion，获取请求版本，并请求设置属性 org.springframework.web.servlet.HandlerMapping.apiVersion 放置请求版本

4. VersionRequestCondition#getMatchingCondition处理请求版本和代码定义版本（国外术语 MappingHandle）对比逻辑

① 获取请求的版本，之前就是之前在请求存放的 org.springframework.web.servlet.HandlerMapping.apiVersion

② 当前 MapperHandler 的版本信息

③ 如果请求版本高于或者等于 MapperHandler 的版本，那么就可以成功匹配

---

启动过程

1. 注册 mvcApiVersionStrategy,详见 EnableWebMvcConfiguration#mvcApiVersionStrategy
   
2. WebMvcConfigurationSupport#requestMappingHandlerMapping 注入mvcApiVersionStrategy

总结

ApiVersionStrategy

API 版本控制的核心策略，其中包含所有与版本控制相关的配置首选项

• 通过API 版本解析器解析请求中的版本信息
• Comparable<?>使用ApiVersionParser解析原始版本值
• 验证请求版本
• 在响应中发送弃用提示

ApiVersionResolver

此策略通过请求解析 API 版本。MVC 配置提供了内置选项，可以从请求头、查询参数、媒体类型参数或 URL 路径解析版本。您也可以使用自定义的ApiVersionResolver

ApiVersionParser

此策略有助于将原始版本值解析为整数值Comparable<?>，从而便于比较、排序和选择版本。默认情况下，内置函数SemanticApiVersionParser 会将版本解析为次版本号major、版本号minor和patch整数值。如果不存在次版本号和补丁版本号，则将其设置为 0。

ApiVersionStrategy

如果请求的版本不受支持，InvalidApiVersionException则会引发异常，并返回 400 响应。默认情况下，支持的版本列表会根据带注解的控制器映射中声明的版本进行初始化，但您可以通过 MVC 配置中的一个标志来关闭此功能，从而仅使用在配置中显式配置的版本。

Validation

默认情况下，启用 API 版本控制时必须指定版本号， MissingApiVersionException否则将返回 400 错误响应。您可以将其设置为可选，此时将使用最新版本。您还可以指定要使用的默认版本

至此，源码部分基本已经看完了，比较简单哈。留个小问题，如果让你使用 早期的版本自定义多版本实现呢？

参考：SpringBoot接口 - 如何提供多个版本接口

结语

写道这里，我试图询问 AI 关于多版本的源码解读时，才发现 AI 的解读也是有时效的。

给我整笑了，这 AI 有点倔强啊！！！

最后也是手动码字；虽然笨拙，但好在完成一些关于 SpringBoot4 博客的确实，因为目前这块儿内容空缺（之所以这么说，其实希望国内博文确实缺乏质量，同时也希望读者尽量多看 Spring 的官方文档和 Github），希望 AI 早点学会吧。如果你看到这里，也希望对于对于你的阅读有点点价值，最后也请求你不要吝啬的点赞支持下吧。

当然如果觉得写的不好的地方还望指正，让我们做正确的事情。

参考资料

• docs.spring.io/spring-fram...
• SpringBoot接口 - 如何提供多个版本接口