Spring 7.0 重磅升級！官方引入 Controller 接口版本控制，終于來了！
在微服務和 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>此外，我們需要配置 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>配置 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[]{"/*"};
}
}- getRootConfigClasses()注冊全局配置類。
- getServletConfigClasses()注冊 Web 層配置類。
- getServletMappings()設置 URL 映射。
根配置類
@Configuration
@ComponentScan({"com.icoderoad.service", "com.icoderoad.repository"})
public class RootConfig {}Web 配置類
@Configuration
@EnableWebMvc
@ComponentScan({"com.icoderoad.controller"})
public class WebConfig {}在 WebConfig 類中，通過 @EnableWebMvc 啟用 Spring MVC 相關功能。
API 版本解析器
為了實現 API 版本管理，我們需要自定義一個解析器來提取請求中的版本信息。
public class CustomWebMvcConfigurer implements WebMvcConfigurer {
@Override
public void configureApiVersioning(ApiVersionConfigurer configurer) {
configurer.useVersionResolver(request -> request.getParameter("v"));
}
}- 該解析器會從請求參數 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...");
}
}當客戶端請求 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 版本演進 的挑戰，現在是時候嘗試這項 官方新功能 了！
