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

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

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

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

Spring Boot 中的 API 版本控制方式

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

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

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

使用場景：

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

示例：

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

現(xiàn)實案例：

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

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

何時使用：

• 需要確保老版本客戶端不受新版本修改的影響
• 客戶端能夠區(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. 請求參數(shù)版本控制

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

使用場景：

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

示例：

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

現(xiàn)實案例：

假設(shè)你為一個新聞網(wǎng)站開發(fā) REST API，版本 1 返回新聞標(biāo)題和摘要，版本 2 返回新聞標(biāo)題、摘要、作者和發(fā)布時間。如果你不想改變原有 API 路徑結(jié)構(gòu)，可以通過請求參數(shù) version 來區(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. 頭部版本控制

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

使用場景：

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

示例：

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

現(xiàn)實案例：

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

代碼示例：

@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. 接受頭部版本控制

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

使用場景：

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

示例：

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

現(xiàn)實案例：

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

代碼示例：

@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é)論

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

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