如何定義並演進元件之間的合約

當一個元件把介面暴露給外部取用者時,請定義該取用者可以依賴的契約。契約驅動開發指的是就該契約達成共識、讓每一方都對照它來實作,並驗證雙方都履行了各自的義務。

這與規格驅動開發相契合:產品需求建立預期行為;契約定義元件如何協作來交付它;每個元件的實作計畫描述其內部解法。先定義互動邊界,而不是把儲存庫邊界當成設計。

本指南使用既有的 Spec Kit 命令與一般的版本化產出物。它不引入自動的契約同步、跨儲存庫相依性解析,或 release 編排。

何時定義契約

「外部」指的是在該元件實作邊界之外,不一定是在其行程、儲存庫或組織之外。範例包括:

  • 網站呼叫後端 API。
  • 一個服務呼叫另一個服務,或取用其事件。
  • 應用程式使用程式庫或外掛介面。
  • 自動化呼叫 CLI 並解析其輸出。
  • 元件以約定的格式交換檔案。

這個原則適用於單體、模組化應用程式、微服務與其他架構。儲存庫版面不決定是否需要契約。它的形式與細節應與介面相符:小型程式庫可能需要有文件記錄的簽章與行為,而公開的 HTTP API 可能受益於 OpenAPI schema 與可執行的範例。並非每份契約都需要獨立的 schema 或契約註冊表。

契約定義什麼

描述可觀察的義務,讓每一方都能在不依賴對方內部實作的情況下實作:

  • 接受的輸入與產生的輸出,包括格式與驗證規則。
  • 行為與副作用,包括錯誤情況。
  • 相關的互動保證,例如冪等性、事件順序、重試或逾時。
  • 相容性預期、版本管理與棄用政策。
  • 供提供者與取用者使用的範例與驗證準則。

光是 schema 可能無法涵蓋完整的協議。例如,訂單請求的形狀並不能說明重試它是否會建立第二筆訂單。也要把那些語意記錄下來。除非內部資料庫結構或實作選擇真的屬於公開介面的一部分,否則不要暴露它們。

一位權威擁有者

由其中一方擁有權威契約;另一方取用它。通常由暴露介面的元件擁有它。請為每個介面明確指出擁有權,並讓受影響的取用者參與變更的共識。擁有權不代表可以單方面變更。

情境 如何共享契約
雙方在同一個儲存庫中 參照同一份權威檔案或產出物,而不是維護各自獨立的定義。獨立發布的元件仍應記錄它們支援的契約版本。
雙方在不同的儲存庫中 發布有版本的契約產出物/套件供取用者釘住,或把副本同步到每個取用儲存庫中。
取用者保留一份同步副本 記錄其權威來源與確切版本或提交。把副本視為唯讀輸入;在來源處提議變更。

對於 vendored 副本,相鄰的 README 可以記錄來源儲存庫、來源路徑、不可變的修訂或 release 產出物摘要,以及更新程序。套件相依性可以在其 lockfile 中記錄等效資訊。為取用者提供契約產出物的授權存取;他們不需要取得提供者實作儲存庫的存取權。

更新必須是刻意的:在權威來源就變更達成共識、發布一個版本,接著在每個取用者中檢視版本或副本的更新。不要悄悄把所有人同步到「latest」。釘住的契約識別的是一份協議;它不能保證已部署的提供者仍支援它。

使用 Spec Kit 工作流程

  1. 建立意圖並識別介面。用 /speckit.specify 擷取期望的使用者行為。識別哪些元件提供、哪些取用每一次互動。若尚無契約,定義它就是工作的一部分,而不是必須已在其他地方完成的前置條件。
  2. 在相依的實作之前就契約達成共識。在 /speckit.plan 期間,擁有者起草介面契約,並與取用者一起檢視。在任一方對另一方做出假設並實作之前,先解決可觀察行為與相容性問題。之後每一方都能對照約定的版本獨立開發。
  3. 把協議提供給每個受影響的專案。把契約的確切版本與可存取的內容,連同相關的產品需求,一起交給代理。不要假設一個連結就能讓另一個儲存庫的檔案變得可用。每個專案擁有自己的本地 spec.md、plan.md 與 tasks.md;參照契約,而不是複製另一個專案的實作計畫。
  4. 明確規劃驗證。請 /speckit.tasks 包含提供者與取用者的契約測試,包括負面情況。測試可觀察行為,也測試資料形狀。取用者對照 mock 的測試很有用,但不能證明真正的提供者符合契約;請包含提供者驗證與整合驗證。
  5. 實作並驗證每一方。在每個專案中使用 /speckit.implement,接著執行約定的檢查。若實作揭露了契約問題,請修訂權威協議,並對帳受影響的規格、計畫、測試與取用者版本,而不是私下變更某份副本。
  6. 發布相容的實作。追蹤哪些已部署的元件版本支援哪些契約版本。圍繞那些相依性安排推出與回復的順序。對於破壞性變更,在移除取用者仍在使用的行為之前,先就遷移與重疊期達成共識。

當涉及外部介面時,/speckit.plan 本來就會產生以功能為範圍的 contracts/ 產出物。請明確選擇哪份產出物是權威的:某項功能可能在那裡起草一份新契約,或提議變更專案其他位置的既有契約。把核准的來源與版本記錄在功能產出物中。歷史快照與同步副本不是額外的可編輯事實來源,Spec Kit 也不會自動發布或同步它們。

變更後的產出物演進,請見在既有專案中演進規格。

實作範例:跨服務的網站結帳

考慮一個假想的結帳功能,包含一個網站、一個訂單服務與一個庫存服務,各自位於自己的儲存庫中。目前尚無約定的契約。使用者需求是:顧客只有在其品項可以被保留時才能下單,且重試請求不得建立重複的訂單或保留。

先識別並就兩份契約達成共識。以下是摘要;權威產出物還必須定義上面所述的輸入/輸出細節與其他義務。

契約 擁有者/提供者 取用者 可觀察的協議
Orders API 訂單服務 網站 接受帶有冪等鍵的訂單請求;回傳訂單或已定義的失敗;重試不得建立重複訂單。
Inventory API 庫存服務 訂單服務 保留所有請求的品項,或回報庫存不足且不做部分保留;重試不得建立重複保留。

訂單服務在一個介面上是提供者,在另一個介面上是取用者。它擁有 Orders API 契約,而不是 Inventory API 契約。

一種可能的版面,使用同步副本而非套件:

inventory-repo/
  .specify/
  contracts/inventory-api.yaml     # authoritative Inventory API contract
  specs/001-reserve-inventory/

orders-repo/
  .specify/
  contracts/orders-api.yaml        # authoritative Orders API contract
  contracts/inventory-api.yaml     # read-only copy pinned to Inventory API 1.0.0
  contracts/README.md              # source revision and sync procedure
  specs/001-place-order/

website-repo/
  .specify/
  contracts/orders-api.yaml        # read-only copy pinned to Orders API 1.0.0
  contracts/README.md              # source revision and sync procedure
  specs/001-checkout/

這些檔名與版本是示意用的,不是 Spec Kit 要求的版面。每個專案都獨立初始化,並使用一般的 SDD 工作流程:

  1. 庫存團隊與訂單團隊就 Inventory API 1.0.0 達成共識;訂單團隊與網站團隊就 Orders API 1.0.0 達成共識。每位擁有者發布其核准的契約,取用者釘住自己的副本。
  2. 每個團隊對照那些協議,規格化並計畫自己那部分的結帳。網站描述顧客互動,訂單描述下單,庫存描述保留行為。訂單計畫同時考量兩份契約,以及保留與建立訂單之間失敗的情況。
  3. 把每個本地功能規格連結到同一個產品功能 issue 或路線圖條目,並記錄其契約版本與相關的提供者/取用者規格或 PR。本地的功能編號與分支不需要一致。這是可追溯性,不是共用的實作計畫。
  4. 實作並驗證兩個介面,包括重試、庫存不足與失敗。也驗證完整的結帳路徑,以及每個元件的契約義務。
  5. 對於這次首次推出,先讓庫存實作可用,再啟用相依的訂單實作,接著啟用網站結帳。記錄已部署的版本與回復限制;光是發布一份契約,並不會讓其實作變得可用。

若 Orders API 1.1.0 之後加入一個選用的送貨備註,請在 orders-repo 中提議並檢視該變更,驗證與既有取用者的相容性,接著讓網站刻意採用新版本。不要編輯網站的同步副本,捏造訂單服務尚未同意提供的支援。

若三個元件之後移到同一個儲存庫中,同樣的設計仍然成立:直接參照權威契約,而不是同步副本。專案版面與命令指定方式,請見在 Monorepo 中使用 Spec Kit。契約連接的是實作;儲存庫版面只改變該協議的共享方式。

範例:控制平面、資料平面與整合測試

考慮一個管理設定的控制平面專案(r1)、一個在處理流量時套用設定的資料平面專案(r2),以及一個驗證它們互動的整合測試專案(r3)。每個專案都位於自己的儲存庫中。這是同一原則的另一個應用,不是要你必須以這種方式組織系統。

先定義互動

假設控制平面需要把一份設定套用到資料平面,但尚無契約。先就可觀察行為達成共識,再讓任一方對另一方做出假設並實作:

契約關注點 範例協議
輸入 一份設定修訂與酬載,附明確的驗證規則。
輸出 一份確認,識別該修訂以及它是被接受還是已套用;若套用是非同步的,定義呼叫者如何觀察完成。
錯誤 針對無效設定與過時修訂的已定義回應,並讓先前有效的設定保持作用中。
行為 重試相同的修訂與酬載不會套用兩次;以不同的酬載重複使用同一修訂會被拒絕。
相容性 識別支援的契約版本,並在遷移期間保留既有呼叫者仍依賴的行為。

在這個範例中,r2 暴露介面並擁有權威契約。r1 團隊參與達成共識,並取用一個釘住的版本。r3 團隊使用同一個版本來驗證互動,包括無效輸入、重試,以及與受支援實作的相容性。測試是協議的證據,而不是與之競爭的另一份定義。

每個專案都保留自己的實作或測試計畫。參照共用的產品意圖與契約版本,不需要總括儲存庫、一致的分支名稱,或跨三個儲存庫的原子提交。

刻意演進已約定的契約

下面的推出順序改編自 TongyiDai 貢獻的契約演進指引。它假設初始的互動契約已經達成共識並在使用中。

假設提供者與取用者同意加入一個新的選用設定欄位。明確規劃它的相容採用:

  1. 發布相容的變更。在 r2 中更新權威契約,給它一個明確的版本,並發布 schema 與相容性 fixture。驗證省略該欄位時能保留既有行為。
  2. 先部署支援,再啟用使用。若 r1 需要 r2 的新行為,先以同時支援新舊取用者的模式部署 r2。只有到那時,才在 r1 中啟用相依的行為。這個順序依循的是介面相依性,而不是儲存庫名稱或 PR 合併順序。
  3. 準備具版本意識的整合測試。及早加入 r3 的涵蓋範圍,依支援的契約版本或明確的能力來選擇預期,而不是依分支名稱。讓既有的相容性檢查保持必要。一旦相容的實作可用,在啟用功能之前,讓新的端到端關卡成為必要;啟用後不要悄悄略過它。
  4. 以不可變的參照追蹤就緒狀態。既有的 issue 或路線圖可以把核准的契約、提供者與取用者的 release、端到端結果,以及舊路徑的移除準則,連結到確切的提交或 release 產出物。區分已合併的變更與已部署、就緒的實作。
  5. 保留回復路徑。對於這種提供者優先的推出,在回復提供者之前,先停用或回復取用者的新行為。也要檢查持久化狀態與設定的相容性;光是反轉部署順序並不能還原資料變更。只有在確認沒有受支援的取用者仍依賴舊契約後,才在後續的清理中移除它。

若破壞性變更無可避免,請擴大支援以允許遷移,刻意移動取用者,然後才淘汰舊行為。發布有版本的契約並記錄就緒狀態,並不會把獨立的部署變成一個交易。這些是團隊維護的協議與檢查,不是新的 Spec Kit 相依性解析器或 release 編排器。