OpenAPI Diff

這個對比工具檢查什麼——以及「破壞性」到底是什麼意思

一項變更之所以是破壞性的，是因為一個嚴格按舊規範寫對的用戶端，不改自己一行程式碼，就可能在新規範下失敗。頁面上的每一個判斷都由這個定義驅動。刪除路徑或操作是破壞性的，因為現有的呼叫無處可去。刪除回應狀態碼——尤其是 2xx——是破壞性的，因為用戶端的錯誤處理正是圍繞舊的狀態碼集合編寫的。新增一個必填參數或必填的請求屬性是破壞性的，因為昨天的合法請求會突然被拒絕。改變欄位的類型或格式是破壞性的，因為剖析器、驗證器和生成的 SDK 都按宣告的類型工作。移除列舉值是破壞性的，因為用戶端可能仍會傳送它，或者儲存著無法再解釋的資料。其餘一切——新端點、可選參數、新的回應欄位、新的列舉值、新的狀態碼——都被報告為非破壞性：舊用戶端繼續可用，哪怕它暫時還用不上新能力。

比較是結構層面的，不是文字層面的。在比較之前，兩份文件都會被正規化為同一個模型：每條路徑和每個操作、按名稱與位置索引的參數、請求正文與每個回應都被歸約為一個模式簽名——由類型、格式、屬性名、必填清單和列舉值遞迴構建的確定性摘要，本地 $ref 引用會被展開。正因如此，調整鍵的順序、重排空白或重寫所有描述文字都會得到一個空的對比結果：這些都不改變合約。也正因如此，埋在被引用模式三層深處的一處變更仍然會被找到——簽名展開的是引用本身，而不是僅僅比較它的名字。

這裡接受兩種輸入形態，因為生態裡兩種都有人發布：先按 JSON 嘗試剖析，失敗時再按 YAML 剖析——大多數手寫的 OpenAPI 文件用的正是 YAML。Swagger 2.0 文件同樣可用，包括它的 in: body 參數和每個回應自帶的模式。這裡刻意沒有線上抓取、也沒有上傳：像處理 HAR 擷取檔案 一樣貼上文件或拖入檔案即可，而且對比是在你按下按鈕時才執行——而不是每次按鍵都執行——所以貼上兩份很大的規範也不會卡頓。

把結果當作發布門檻來用，而不是裝飾。在審查中，破壞性清單就是議程：每一項都需要修復、提升版本號、給出棄用窗口，或者留下一份「這次破壞是有意為之且已通知」的書面決定。非破壞性清單就是變更日誌的草稿。把對比結果匯出為 JSON，可以把這份決定歸檔在版本旁邊；可複製的摘要可以直接放進拉取請求——這與對待 webhook 合約變更 是同一套紀律：一份被悄悄改動的負載會同時破壞每一個訂閱方。

誠實的限制，明確說出來。這個對比工具比較的是宣告過的合約：它看不見規範沒有宣告的行為，例如欄位類型不變但含義變了、新增的業務規則、更緊的限流，或者用戶端（不明智地）在剖析的錯誤訊息文字。工具會跟隨本地引用並在有限深度內比較模式，因此病態的深層嵌套或互相遞迴的模式會被摘要化，而不是無限展開下去。而且，零破壞性變更的對比結果並不能保證升級一定安全——它證明的是文件化的合約沒有變，這恰恰是部署之前值得擁有的證據。