Spring 7.0 重磅升级！官方引入 Controller 接口版本控制，终于来了！-51CTO.COM

在微服务和 API 经济盛行的今天，API 版本管理早已成为后端开发的刚需。每当接口升级，如何兼容老版本、同时支持新功能迭代，是开发者面临的头号挑战。以往，Spring 并未提供官方的 API 版本控制方案，开发者只能依赖自定义注解、请求头解析、URL 版本标识等方式来实现版本管理。

好消息来了！ Spring 7.0 重磅升级，终于在 Spring MVC 中引入了原生的 API 版本控制机制，这意味着我们可以用更优雅、官方推荐的方式来管理 API 版本，而无需额外的复杂配置！

本篇文章将基于 Spring Boot 3.4，带你快速上手 Spring 7.0 新增的 API 版本控制功能，并通过实战案例详细讲解如何实现零侵入、高兼容的 API 版本管理。

API 接口版本管理概述

在设计 API 接口时，我们通常需要引入版本控制机制，以确保不同版本的 API 互不干扰，同时兼容老版本用户。常见的版本标识方式包括：

直接在 URL 中添加版本号，例如 /v1/api/query、/v2/api/query。
在 HTTP 请求头中加入特定字段，例如 X-API-Version: 1.0。

这种方式能确保 API 在升级过程中保持兼容性，并允许新功能的无缝迭代。然而，在 Spring 框架的早期版本中，并没有官方支持 API 版本管理的内置机制。直至 Spring 7.0.0 版本，官方才正式引入 API 版本控制特性，目前该功能仍处于 7.0.0-M3 里程碑阶段。

实战：基于 Spring Boot 3.4 体验 API 版本控制

在本案例中，我们将使用 Spring Boot 3.4 版本，并结合 Spring 7.0.0-M3 里程碑版本，实现 API 版本控制功能。

环境准备

在 pom.xml 中添加相关依赖：

<properties>
    <spring.version>7.0.0-M3</spring.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-context</artifactId>
        <version>${spring.version}</version>
    </dependency>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-web</artifactId>
        <version>${spring.version}</version>
    </dependency>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-webmvc</artifactId>
        <version>${spring.version}</version>
    </dependency>
</dependencies>1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.

此外，我们需要配置 Spring 7.0.0 里程碑版本的仓库：

<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>1.
2.
3.
4.
5.
6.
7.
8.
9.
10.

配置 Web 环境

为 Spring MVC 配置 Web 应用初始化器，使其支持 API 版本控制。

public class WebAppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {
    @Override
    protected Class<?>[] getRootConfigClasses() {
        return new Class<?>[]{RootConfig.class};
    }


    @Override
    protected Class<?>[] getServletConfigClasses() {
        return new Class<?>[]{WebConfig.class};
    }


    @Override
    protected String[] getServletMappings() {
        return new String[]{"/*"};
    }
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.

getRootConfigClasses()注册全局配置类。
getServletConfigClasses()注册 Web 层配置类。
getServletMappings()设置 URL 映射。

根配置类

@Configuration
@ComponentScan({"com.icoderoad.service", "com.icoderoad.repository"})
public class RootConfig {}1.
2.
3.

Web 配置类

@Configuration
@EnableWebMvc
@ComponentScan({"com.icoderoad.controller"})
public class WebConfig {}1.
2.
3.
4.

在 WebConfig 类中，通过 @EnableWebMvc 启用 Spring MVC 相关功能。

API 版本解析器

为了实现 API 版本管理，我们需要自定义一个解析器来提取请求中的版本信息。

public class CustomWebMvcConfigurer implements WebMvcConfigurer {
    @Override
    public void configureApiVersioning(ApiVersionConfigurer configurer) {
        configurer.useVersionResolver(request -> request.getParameter("v"));
    }
}1.
2.
3.
4.
5.
6.

该解析器会从请求参数 v 中解析 API 版本号。
若未指定版本号，则会抛出 InvalidApiVersionException 异常。

定义 API 接口

我们在 @RequestMapping 注解中使用 version 属性来定义 API 版本。

@RestController
@RequestMapping("/api")
public class ApiController {
    @GetMapping(value = "/query", version = "1.0.0")
    public ResponseEntity<String> queryV1() {
        return ResponseEntity.ok("query api v1.0.0...");
    }


    @GetMapping(value = "/query", version = "2.0.0")
    public ResponseEntity<String> queryV2() {
        return ResponseEntity.ok("query api v2.0.0...");
    }
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.

当客户端请求 API 时，若 v 参数值与 version 定义的值匹配，则该接口会被调用。例如：

访问 /api/query?v=1.0.0，返回 query api v1.0.0...
访问 /api/query?v=2.0.0，返回 query api v2.0.0...

若请求的 v 参数不匹配任何版本，则会抛出 InvalidApiVersionException。

结论

Spring 7.0 的 API 版本控制功能，终于为后端开发者带来了官方级的最佳实践，相比传统的 URL 版本管理或自定义解析方案，这种方式更优雅、直观、稳定，并且可以无缝集成到现有的 Spring MVC 体系中。

从实战案例可以看出，Spring 7.0 版本控制方案具有以下核心优势：

官方支持，减少自定义逻辑，不再依赖额外插件或第三方库。
多种版本解析方式（URL、Header、Query 参数），兼容不同场景。
更灵活的 API 演进策略，让接口升级更加平滑，避免影响老用户。

Spring 7.0 的到来，不仅简化了 API 版本管理，也为企业级开发提供了更强大的支持。如果你正在使用 Spring Boot 3.4，并且面临 API 版本演进的挑战，现在是时候尝试这项官方新功能了！