API 合約
合約是你對無法控制也無法修復的程式碼所做出的承諾。這就是 API 變更與內部重構不同的地方:犯錯的成本是由別人在你無法選擇的時間點來承擔。
設計
將資源命名為名詞,讓方法承載動詞。對事物本身建模,而不是目前顯示它的螢幕——圍繞當今 UI 設計的酬載,在下一次重新設計時就會出錯。
審慎考量你暴露的內容。你回傳的每個欄位,都必須持續回傳。內部識別碼、資料列版本與實作細節會將你的結構描述洩漏到呼叫端的程式碼中,並將其凍結在那裡。
讓操作具有等冪性,以便呼叫端可以重試——任何可透過網路觸及的操作都應如此。對於任何建立或收費的操作,給予呼叫端一個等冪金鑰,這樣逾時後的重試就不會造成重複。
回傳一致的錯誤模型:一個穩定的機器可讀碼、一個人類可讀的訊息,以及驗證失敗時所參照的欄位。呼叫端會根據該碼進行分支判斷,因此它是合約的一部分——即使形狀不變,變更該碼仍屬破壞性變更。
從第一個版本就對每個清單進行分頁。一個回傳所有資料的端點,在資料表成長前都能正常運作,但之後就會對擁有最多資料的客戶造成失敗。當資料列同時插入時,偏好使用游標而非偏移量。
什麼會破壞呼叫端
以下情況,無論結構描述語言允許與否,皆屬破壞性變更:
- 移除或重新命名欄位、端點、方法或列舉值。
- 將可選請求欄位改為必填,或縮小欄位可接受的值範圍。
- 變更型別,包括將整數改為字串,或將單一值改為清單。
- 在保留欄位名稱與型別的情況下,變更既有欄位的意義——這是最糟糕的情況,因為沒有明顯的錯誤,資料只會悄悄地出錯。
- 新增必填請求欄位。
- 針對既有條件變更錯誤碼或 HTTP 狀態碼。
- 緊縮預設值,或變更省略欄位時的行為。
安全:新增可選請求欄位、新增回應欄位、新增端點或方法、新增列舉值——僅當每個消費者都已能容忍未知值時才安全——請驗證這一點,而非直接假設。
在 protobuf 中,切勿重複使用或重新編號欄位標籤,並在移除欄位時保留該標籤與名稱。重複使用的標籤會將舊資料解碼到新欄位中,並悄悄地破壞它。
安全地變更合約
先新增再移除,並讓兩者並存至少一個版本:
- 將新欄位或方法與舊的並列。
- 同時寫入兩者,讀取時先嘗試新的,失敗時再退回舊的。
- 遷移消費者,並確認每個消費者都已轉移。
- 在後續版本中移除舊的路徑。
僅在資源的意義真正改變時才進行版本化,而非每次新增都版本化。每次變更都版本化會倍增你必須維持活躍的表面積。
部署順序
產生的程式碼與伺服器是分開部署的,而這個間隔就是中斷發生的地方。先推出能夠容忍兩種形狀的那一方:消費者在生產者發出新欄位之前就接受它,生產者在呼叫端發送新請求之前就接受它。
當結構描述透過閘道、代理伺服器或產生的客戶端共享時,路徑中的每個元件都需要重新產生與重新部署。一個已新增至服務但未新增至其前一層的欄位,會在到達呼叫端之前消失,而服務自身的測試將不會注意到這一點。
驗證
在變更形狀之前,先檢查實際的消費者——搜尋呼叫端,而非僅相信合約的文件。
測試合約本身:一個斷言序列化後形狀的測試,可以捕捉到在 handler 的單元測試中完全無法察覺的意外重新命名。