在微服務(wù)和 API 經(jīng)濟(jì)盛行的今天，API 版本管理 早已成為后端開發(fā)的 剛需。每當(dāng)接口升級(jí)，如何 兼容老版本、同時(shí)支持 新功能迭代，是開發(fā)者面臨的 頭號(hào)挑戰(zhàn)。以往，Spring 并未提供官方的 API 版本控制方案，開發(fā)者只能依賴 自定義注解、請(qǐng)求頭解析、URL 版本標(biāo)識(shí) 等方式來(lái)實(shí)現(xiàn)版本管理。

好消息來(lái)了！ Spring 7.0 重磅升級(jí)，終于在 Spring MVC 中引入了原生的 API 版本控制機(jī)制，這意味著我們可以用更優(yōu)雅、官方推薦的方式來(lái)管理 API 版本，而無(wú)需額外的復(fù)雜配置！

本篇文章將基于 Spring Boot 3.4，帶你快速上手 Spring 7.0 新增的 API 版本控制功能，并通過(guò)實(shí)戰(zhàn)案例詳細(xì)講解如何實(shí)現(xiàn) 零侵入、高兼容的 API 版本管理。

API 接口版本管理概述

在設(shè)計(jì) API 接口時(shí)，我們通常需要引入版本控制機(jī)制，以確保不同版本的 API 互不干擾，同時(shí)兼容老版本用戶。常見的版本標(biāo)識(shí)方式包括：

• 直接在 URL 中添加版本號(hào)，例如 /v1/api/query、/v2/api/query。
• 在 HTTP 請(qǐng)求頭中加入特定字段，例如 X-API-Version: 1.0。

這種方式能確保 API 在升級(jí)過(guò)程中保持兼容性，并允許新功能的無(wú)縫迭代。然而，在 Spring 框架的早期版本中，并沒(méi)有官方支持 API 版本管理的內(nèi)置機(jī)制。直至 Spring 7.0.0 版本，官方才正式引入 API 版本控制特性，目前該功能仍處于 7.0.0-M3 里程碑階段。

實(shí)戰(zhàn)：基于 Spring Boot 3.4 體驗(yàn) API 版本控制

在本案例中，我們將使用 Spring Boot 3.4 版本，并結(jié)合 Spring 7.0.0-M3 里程碑版本，實(shí)現(xiàn) API 版本控制功能。

環(huán)境準(zhǔn)備

在 pom.xml 中添加相關(guān)依賴：

<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 里程碑版本的倉(cāng)庫(kù)：

<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 環(huán)境

為 Spring MVC 配置 Web 應(yīng)用初始化器，使其支持 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()注冊(cè)全局配置類。
• getServletConfigClasses()注冊(cè) Web 層配置類。
• getServletMappings()設(shè)置 URL 映射。

根配置類

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

Web 配置類

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

在 WebConfig 類中，通過(guò) @EnableWebMvc 啟用 Spring MVC 相關(guān)功能。

API 版本解析器

為了實(shí)現(xiàn) API 版本管理，我們需要自定義一個(gè)解析器來(lái)提取請(qǐng)求中的版本信息。

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

• 該解析器會(huì)從請(qǐng)求參數(shù) v 中解析 API 版本號(hào)。
• 若未指定版本號(hào)，則會(huì)拋出 InvalidApiVersionException 異常。

定義 API 接口

我們?cè)?nbsp;@RequestMapping 注解中使用 version 屬性來(lái)定義 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...");
    }
}

當(dāng)客戶端請(qǐng)求 API 時(shí)，若 v 參數(shù)值與 version 定義的值匹配，則該接口會(huì)被調(diào)用。例如：

• 訪問(wèn) /api/query?v=1.0.0，返回 query api v1.0.0...
• 訪問(wèn) /api/query?v=2.0.0，返回 query api v2.0.0...

若請(qǐng)求的 v 參數(shù)不匹配任何版本，則會(huì)拋出 InvalidApiVersionException。

結(jié)論

Spring 7.0 的 API 版本控制 功能，終于為后端開發(fā)者帶來(lái)了 官方級(jí)的最佳實(shí)踐，相比傳統(tǒng)的 URL 版本管理 或 自定義解析方案，這種方式更優(yōu)雅、直觀、穩(wěn)定，并且可以無(wú)縫集成到現(xiàn)有的 Spring MVC 體系 中。

從實(shí)戰(zhàn)案例可以看出，Spring 7.0 版本控制方案具有以下核心優(yōu)勢(shì)：

• 官方支持，減少自定義邏輯，不再依賴額外插件或第三方庫(kù)。
• 多種版本解析方式（URL、Header、Query 參數(shù)），兼容不同場(chǎng)景。
• 更靈活的 API 演進(jìn)策略，讓接口升級(jí)更加平滑，避免影響老用戶。

Spring 7.0 的到來(lái)，不僅簡(jiǎn)化了 API 版本管理，也為企業(yè)級(jí)開發(fā)提供了更強(qiáng)大的支持。如果你正在使用 Spring Boot 3.4，并且面臨 API 版本演進(jìn) 的挑戰(zhàn)，現(xiàn)在是時(shí)候嘗試這項(xiàng) 官方新功能 了！