隨著應(yīng)用程序的不斷演進(jìn)，API 也會(huì)隨之變化。在這個(gè)過(guò)程中，可能需要：

• 添加新的字段
• 更改響應(yīng)格式
• 棄用舊的功能而不破壞現(xiàn)有客戶端

這就是 API 版本控制的作用所在。

API 版本控制是一種在支持舊版本的同時(shí)管理 API 更改的策略。在 Spring Boot 中，這可以通過(guò)多種方式實(shí)現(xiàn)，每種方式適用于不同的用例。本文將深入探討 Spring Boot 中實(shí)現(xiàn) API 版本控制的四種主要策略，并提供最佳實(shí)踐，幫助你更好地管理 API 版本變化。

Spring Boot 中的 API 版本控制方式

API 版本控制主要有四種常見(jiàn)的實(shí)現(xiàn)方式，分別是：URI 版本控制、請(qǐng)求參數(shù)版本控制、頭部版本控制（自定義 HTTP 頭部）以及接受頭部版本控制（基于 MIME 類型的內(nèi)容協(xié)商）。除了這四種標(biāo)準(zhǔn)方式，實(shí)際應(yīng)用中可能還會(huì)出現(xiàn)一些其他的組合策略。

1. URI 版本控制（路徑方式）

URI 版本控制直接在 URL 路徑中指定版本號(hào)，例如 /api/v1/products，這是一種常見(jiàn)且直觀的方式，能夠很好地支持多版本 API。

使用場(chǎng)景：

• 需要保持向后兼容性
• 客戶端對(duì)版本控制方式?jīng)]有強(qiáng)烈要求

示例：

/api/v1/products
/api/v2/products

現(xiàn)實(shí)案例：

假設(shè)你正在為一個(gè)電子商務(wù)平臺(tái)開(kāi)發(fā) API。最初，/api/v1/products 返回的是基礎(chǔ)的商品信息。隨著業(yè)務(wù)的發(fā)展，你需要返回更多的詳細(xì)信息，例如庫(kù)存、供應(yīng)商信息等，而不希望影響使用舊版 API 的客戶端。

你可以通過(guò)新版本接口 /api/v2/products 返回更多的數(shù)據(jù)，而老版本客戶端仍然使用 /api/v1/products，不會(huì)受到影響。

何時(shí)使用：

• 需要確保老版本客戶端不受新版本修改的影響
• 客戶端能夠區(qū)分不同版本
• 想要清晰地指定 API 版本

代碼示例：

v1 版本控制器：

@RestController
@RequestMapping("/api/v1/products")
public class ProductV1Controller {


    @GetMapping
    public List<String> getProducts() {
        return List.of("iPhone", "Samsung Galaxy", "OnePlus");
    }
}

v2 版本控制器：

@RestController
@RequestMapping("/api/v2/products")
public class ProductV2Controller {


    @GetMapping
    public List<Product> getProducts() {
        return List.of(
            new Product("iPhone", 999.99, "In Stock"),
            new Product("Samsung Galaxy", 899.99, "Out of Stock")
        );
    }
}

2. 請(qǐng)求參數(shù)版本控制

在這種策略中，API 版本通過(guò)查詢參數(shù)傳遞，例如 ?version=1。這種方式對(duì)于不希望改變 API 路徑的場(chǎng)景特別適用。

使用場(chǎng)景：

• 需要保持 URL 清晰，不修改路徑結(jié)構(gòu)
• 版本控制是可選的或臨時(shí)的

示例：

GET /api/products?version=1
GET /api/products?version=2

現(xiàn)實(shí)案例：

假設(shè)你為一個(gè)新聞網(wǎng)站開(kāi)發(fā) REST API，版本 1 返回新聞標(biāo)題和摘要，版本 2 返回新聞標(biāo)題、摘要、作者和發(fā)布時(shí)間。如果你不想改變?cè)?API 路徑結(jié)構(gòu)，可以通過(guò)請(qǐng)求參數(shù) version 來(lái)區(qū)分版本。

代碼示例：

v1 版本控制器：

@RestController
@RequestMapping("/api/products")
public class ProductController {


    @GetMapping(params = "version=1")
    public List<String> getProductsV1() {
        return List.of("iPhone", "Samsung Galaxy", "Pixel");
    }


    @GetMapping(params = "version=2")
    public List<Product> getProductsV2() {
        return List.of(
            new Product("iPhone", 999.99, "In Stock"),
            new Product("Samsung Galaxy", 899.99, "Out of Stock")
        );
    }
}

3. 頭部版本控制

這種策略通過(guò)自定義 HTTP 頭部傳遞 API 版本信息，例如 X-API-VERSION: 1。這對(duì)于希望隱藏版本控制信息的應(yīng)用非常適用，常見(jiàn)于移動(dòng)應(yīng)用或合作方 API。

使用場(chǎng)景：

• 隱藏版本控制信息
• 內(nèi)部應(yīng)用或合作方的 API

示例：

GET /api/products
X-API-VERSION: 1

現(xiàn)實(shí)案例：

假設(shè)你為移動(dòng)銀行應(yīng)用提供一個(gè)交易記錄查詢接口，你不希望在 URL 或查詢參數(shù)中暴露版本信息。你可以通過(guò)請(qǐng)求頭 X-API-VERSION 來(lái)指定版本信息。

代碼示例：

@RestController
@RequestMapping("/api/products")
public class ProductHeaderVersionController {


    @GetMapping(headers = "X-API-VERSION=1")
    public List<String> getProductsV1() {
        return List.of("iPhone", "Samsung Galaxy", "Pixel");
    }


    @GetMapping(headers = "X-API-VERSION=2")
    public List<Product> getProductsV2() {
        return List.of(
            new Product("iPhone", 999.99, "In Stock"),
            new Product("Samsung Galaxy", 899.99, "Out of Stock")
        );
    }
}

4. 接受頭部版本控制

這種版本控制方式通過(guò) HTTP 請(qǐng)求中的 Accept 頭部來(lái)指定版本。例如，Accept: application/vnd.company.app-v1+json，表示客戶端希望獲取版本 1 的資源。

使用場(chǎng)景：

• 完全遵循 RESTful 設(shè)計(jì)原則
• 希望保持 URL 清晰（不包含版本號(hào)）
• 涉及數(shù)據(jù)格式變化時(shí)，例如響應(yīng)數(shù)據(jù)格式為 JSON 或 XML

示例：

GET /api/products
Accept: application/vnd.company.app-v1+json

現(xiàn)實(shí)案例：

假設(shè)你為一個(gè)金融技術(shù)平臺(tái)提供 API，版本 1 返回總余額，版本 2 返回按類別劃分的余額。你不希望在 URL 中暴露版本號(hào)，同時(shí)希望遵循嚴(yán)格的 RESTful 設(shè)計(jì)。

代碼示例：

@RestController
@RequestMapping("/api/products")
public class ProductMimeVersionController {


    @GetMapping(produces = "application/vnd.company.app-v1+json")
    public List<String> getProductsV1() {
        return List.of("iPhone", "Samsung Galaxy", "Pixel");
    }


    @GetMapping(produces = "application/vnd.company.app-v2+json")
    public List<Product> getProductsV2() {
        return List.of(
            new Product("iPhone", 999.99, "In Stock"),
            new Product("Samsung Galaxy", 899.99, "Out of Stock")
        );
    }
}

結(jié)論

通過(guò)合理選擇 API 版本控制策略，可以有效避免 API 更新時(shí)對(duì)現(xiàn)有用戶造成的影響。每種版本控制方式都有其獨(dú)特的優(yōu)缺點(diǎn)，因此開(kāi)發(fā)者需要根據(jù)具體需求選擇最合適的策略。無(wú)論是 URI 版本控制、請(qǐng)求參數(shù)版本控制、頭部版本控制，還是接受頭部版本控制，都可以幫助開(kāi)發(fā)者靈活地管理 API 的版本變化，確保 API 的演進(jìn)不會(huì)打破已有客戶端的兼容性。

希望本文能幫助你更好地理解 Spring Boot 中的 API 版本控制，并能夠在實(shí)際項(xiàng)目中靈活應(yīng)用這些技術(shù)，滿足不同版本控制需求。