在軟體系統的生命週期中，「變更是唯一的不變」。

然而，當你的 API 已經發布給數以萬計的行動端 App、第三方開發者或企業客戶使用時，任何一個看似微小的欄位重命名（如將 user_name 改為 username）或型別變更（如將數字改為字串），都會直接導致舊版客戶端崩潰。

API 版本控制（API Versioning） 是保證系統可持續演進的最關鍵基礎設施。

本文將帶你深入剖析 4 大主流版本控制策略，並拆解全球頂級 API 典範 Stripe 如何在單一核心代碼庫下維護數百個歷史 API 版本的黑科技架構。

1. 四大 API 版本控制策略全景對比

四大 API 版本控制策略示意圖展示 URI Path、Custom Header、Accept 內容協商與 Query Parameter 四種版本標註格式。1. URI Path 版本控制 (最常見)GET /api/v1/users/42 ➔ /api/v2/users/422. Custom Header 版本控制 (Stripe)Header: X-API-Version: 2026-09-013. Accept 內容協商 (REST 純粹)Accept: application/vnd.app.v2+json4. Query Parameter (簡單直觀)GET /api/users/42?version=2
版本控制方式具體實現範例優點缺點適用場景
URI Path (路徑)/api/v1/orders ➔ /api/v2/orders直觀清晰、可透過瀏覽器直接點擊、CDN 邊緣快取天然隔離違反 REST 資源純粹性（同一資源有多個 URL）、跨版本重構代碼重複公眾開放 API、大型主版本破壞性重構
Custom Header (標頭)X-API-Version: 2026-09-02保持 URL 乾淨一致、易於語意化日期發布管理無法直接在瀏覽器網址列存取、CDN 需配置 Vary Header企業級內部微服務、B2B SaaS 平台 (Stripe)
Accept 內容協商Accept: application/vnd.app.v1+json完全符合 RESTful HATEOAS 標準語法繁瑣、客戶端接入門檻高、除錯不易學術標準嚴格的 REST 架構
Query Parameter (參數)/api/orders?v=2實現極其簡單、支援預設缺省值URL 雜亂、容易與業務篩選參數混淆臨時過渡、輕量內部專案

2. 什麼是相容變更 vs. 破壞性變更（Breaking Changes）？

2.1 ✅ 安全的向後相容變更（無需升級 API 版本）

  1. 新增可選欄位（Optional Fields）：在 Response JSON 中新增新欄位；
  2. 新增獨立 API 端點：如新增 POST /v1/users/export；
  3. 放寬請求參數約束：將某個原本必填的參數改為可選。

2.2 ❌ 破壞性變更（必須引入新版本管理）

  1. 重新命名或刪除欄位：如將 tele 改為 phone_number；
  2. 修改欄位資料型別：如將 price: 100（整數）改為 price: "100.00"（字串）；
  3. 修改 HTTP 狀態碼語義：如原本返回 404 突然改為返回 200 OK 帶 { "data": null }；
  4. 新增必填請求參數。

3. Stripe 式版本控制架構：雙向變更閘道器（Version Translators）

Stripe 最著名的工程奇蹟在於：用戶在 2017 年註冊時鎖定的 API 版本，在 2026 年依然能完美執行，而後端核心代碼只有一套最新的版本！

Stripe 雙向版本轉換閘道器架構圖展示 2017 舊版請求經 API 轉換層向上相容轉換至最新 2026 商業邏輯，回應再向下修補還原為 2017 格式。歷史客戶端 (發起 2017-05-10 版本請求)API 閘道轉換層 (Request Translators: 2017 ➔ 2019 ➔ 2026)按版本更新鏈依序向上補充預設值與欄位映射核心業務微服務 (永遠只運行最新 2026 商業邏輯)單一主幹代碼庫・零歷史相容包袱API 閘道轉換層 (Response Translators: 2026 ➔ 2019 ➔ 2017)依序向下修補舊欄位格式・剃除新版專屬不可識別欄位✅ 舊版客戶端收到 100% 相容的 2017 格式資料！
  • 優勢：開發團隊只需要維護最新版本的主幹代碼；每個歷史版本的微小差異被封裝為單獨的轉換函式（Translators），極大降低了多版本共存時的維護地獄。

4. API 廢棄（Deprecation）與退役生命週期治理

  1. Sunset Header 標準規範（RFC 8594）： 在即將廢棄的 API 回應中加入標準標頭： 
    Deprecation: @1756800000
Sunset: Wed, 02 Sep 2026 00:00:00 GMT
Link: <https://docs.carlstack.dev/migration-v2>; rel="sunset"
  2. 主動通知與流量監控：在 API 閘道器統計各個版本的調用量，定期向仍在使用老舊版本的用戶發送自動化遷移提醒。

5. 總結

  • 對外公開 API 推薦 URI Path（/v1/）：簡單直觀，生態工具支援最完美。
  • 複雜平台推薦 Date-based Header（X-Version: YYYY-MM-DD）：搭配雙向轉換層，兼顧靈活性與相容性。
  • 嚴格遵守相容性鐵律：只增不刪、廢棄先行、提供充足的遷移過渡期。