別再亂搞 API 版本管理了！這些坑你踩過幾個？
在日常開發中，API版本的迭代幾乎是無法避免的事情。最近在項目中，我們遇到了需要在不影響舊客戶端的前提下，發布新版接口的需求。
一開始，我也用了最常見的做法：
GET /v1/products
GET /v2/products乍一看很直觀，路徑一目了然，新老版本分開，大家都這么干，好像也沒毛病。
可惜，這種方式看似簡單，實則問題重重。
路徑版本化的“表面光鮮”
我們可能會這么設計控制器：
@RestController
@RequestMapping("/v1/products")
public class ProductControllerV1 {
// V1邏輯
}
@RestController
@RequestMapping("/v2/products")
public class ProductControllerV2 {
// V2邏輯
}這在項目初期確實很“快”。但是隨著版本增多，問題接踵而至：
- 控制器、測試、文檔全要復制一份；
- 每多一個版本，代碼重復度、維護成本、測試開銷都指數上升；
- 文檔冗余、客戶端混亂、接口路徑不穩定。
URL版本控制違背了 REST 的設計初衷
根據 RESTful 的核心理念：
URI 是資源的永久地址，應保持穩定性。
路徑中包含版本號，就像是給圖書的 ISBN 每年都改一次，不僅違背設計初衷，還容易造成客戶端的嚴重耦合。
舉個例子：
如果我們每年都改接口路徑：
/v1/products
/v2/products
/v3/products
/legacy/products老系統不能刪除，新系統又要兼容，最終的結果是：
- 控制器臃腫不堪；
- 老版本無法完全淘汰；
- 文檔極度冗余；
- 客戶端升級困難；
- 出現 404 時，用戶只能摸黑報 bug。
更優雅的做法：基于請求頭的版本控制
相比 URL 版本，通過 HTTP Header 來傳遞版本信息更貼合 REST 設計原則。
接口路徑不變：
GET /products版本通過 Accept 頭協商：
- 請求 V1：
Accept: application/vnd.icoderoad.v1+json- 請求 V2：
Accept: application/vnd.icoderoad.v2+jsonSpring Boot 3.4 實現方式
項目結構基于 com.icoderoad 包名：
package com.icoderoad.api.controller;
@RestController
@RequiredArgsConstructor
public class ProductController {
private final VersionProvider versionProvider;
private final IProductService productService;
@GetMapping(value = "/products", produces = {
"application/vnd.icoderoad.v1+json",
"application/vnd.icoderoad.v2+json"
})
public ResponseEntity<List<IProductResponseDto>> getProducts(
@RequestHeader(value = "Accept", defaultValue = "application/vnd.icoderoad.v1+json") String acceptHeader) {
Version version = versionProvider.identifyVersion(acceptHeader);
List<IProductResponseDto> products = productService.getProducts(version);
return ResponseEntity.ok(products);
}
}VersionProvider 示例：
package com.icoderoad.api.version;
@Component
public class VersionProvider {
public Version identifyVersion(String acceptHeader) {
if (acceptHeader.contains("v2")) {
return Version.V2;
}
return Version.V1;
}
}響應 DTO 接口：
public interface IProductResponseDto {
String getName();
}不同版本可以實現不同的 DTO，比如 ProductV1Dto, ProductV2Dto。
優點解析
優勢 | 說明 |
URI 穩定 |
永遠不會改變 |
向后兼容 | 多版本共存，只需判斷 Header |
更適配緩存 | 請求路徑不變，緩存更好命中 |
遵循 REST 規范 | 與 Fielding 的 REST 理論保持一致 |
擴展建議：再往前走一步
增加 Swagger 兼容支持
使用 springdoc-openapi，通過 API Group 實現版本文檔拆分展示：
springdoc:
group-configs:
- group: v1
paths-to-match: /products
produces-to-match: application/vnd.icoderoad.v1+json
- group: v2
paths-to-match: /products
produces-to-match: application/vnd.icoderoad.v2+json自定義注解 + AOP 做更細粒度的控制
你也可以用注解標識不同版本的方法，再配合 AOP 在運行時動態路由調用，非常優雅。
那 URL 版本化有沒有場景？
有！但 僅限以下兩種情況：
- 內部系統或微服務之間通信，版本變動可控
- 資源結構發生破壞性變化，無法向后兼容（例如合規要求）
除此之外，請盡量使用 Header 版本控制。
總結
- URI 是資源的“身份證”，不應頻繁變化；
- 版本控制建議通過 HTTP Header 實現；
- 教育前端和客戶端團隊理解 Accept Header 的重要性；
- 采用統一控制器，降低代碼重復，維護成本更低。
如果你還在用 /v1/xxx 的方式管理版本，或許可以思考下換個方式，擁抱更優雅的 REST 實踐。
