API介面版本控制的實現方式

語言: CN / TW / HK

軟體系統在整個生命週期當中會根據需求的不斷變化進行不斷的迭代更新,因此服務端對外提供的介面儘管功能未發生變化,但是實現的邏輯,程式碼也在不斷的變化。如果只是簡單的變化,對於介面呼叫者來說是無感知的,但是通常會出現一些突破性的變化,例如:

  • 介面新增欄位
  • 介面欄位型別變更
  • 介面欄位由非必傳變成必傳

上述情況的出現,對於介面呼叫者來說必然是存在強烈感知的,通常為了減少介面呼叫者的感知,服務端程式碼就存在同樣功能的介面,多個版本的情況,就出現了介面版本控制這個問題。

版本控制及實現方式:

1 請求引數控制

例如在HTTP請求當中不修改請求路徑的情況下新增引數:

在請求的引數當中新增版本引數: HTTP://XXX.COM?version=1

在請求頭HEADER當中新增版本引數:version:1

在請求頭Content-Type: application/v1.json

以上三種均可以在請求引數當中進行版本的控制,並且不修改請求路徑,相關程式碼實現如下:

@GetMapping(value = "test",params = {"version=1"},headers = {"version=1"},consumes = {"Content-Type=application/v1.json"})
   public String getT2() {
       return "123456";
   }

2 URL路徑控制

即版本是請求URL的一部分:例如:/v1/api/getUser, /api/getUser/v1。

3 域名服務控制

即請求路徑不變,域名發生變化:v1.api.hjljy.cn/getUser,v2.api.hjljy.cn/getUser

總結

無論選用哪一種實現方式,同一個功能的介面版本不宜過多,避免造成較高的維護成本,同時儘可能的保證介面版本的穩定性和可讀性(便於查詢和排錯)