後端改版，前端崩潰？用 API Versioning 與 Breaking Change 檢測終結「版本地獄」
週五下午的慘案
這是一個真實發生在許多團隊的故事：
週五下午四點，後端工程師小明心想：「這個 userAge 欄位好像沒在用了，而且我們已經有 birthDate 了，為了讓 API 乾淨一點，我把它刪掉好了。」 小明按下 Commit，開心下班過週末。
週五晚上七點，客服電話被打爆。所有舊版的 iOS App 用戶在開啟「個人頁面」時全部閃退。 原因很簡單：舊版 App 還在讀取 userAge，但這個欄位突然憑空消失，導致 App 解析 JSON 失敗 (Null Pointer Exception)。
這就是所謂的 Breaking Change (破壞性變更)。 在微服務與前後端分離的架構下，後端工程師往往無法精確知道「誰正在使用我的 API」。靠「通靈」或「口頭詢問」來判斷欄位能不能改，是極度危險的。
今天我們要聊聊，如何用 SmartBear Swagger (SwaggerHub) 來建立一道「防呆機制」。
什麼是 Breaking Change？
簡單來說，就是「會讓客戶端 (Client) 出錯的變更」。 常見的破壞性變更包括：
-
刪除欄位：如上述案例。
-
修改欄位名稱：把
id改成userId。 -
修改資料型別：把字串
"123"改成數字123。 -
新增「必填」參數：原本呼叫不用參數，現在變成一定要傳參數才能動。
反之，如果是「新增一個非必填欄位」，通常被視為安全變更 (Non-breaking change)，因為舊的客戶端只會忽略它，不會報錯。
SmartBear Swagger (SwaggerHub) 的守門員機制
我們不應該依賴工程師的記憶力來避免 Breaking Change。在 SmartBear Swagger (SwaggerHub) (前身是 SwaggerHub) 中，系統內建了強大的自動檢測功能：
1. 存檔前的「紅燈停」
當你在編輯器中修改 OpenAPI Spec 時，Swagger (SwaggerHub) 會即時比對你現在的版本與上一個發布的版本。 如果你試圖刪除一個已存在的 Operation 或欄位，系統會立刻彈出 “Breaking Change” 的紅色警告標章。
這就像是編輯器在對你大喊：「嘿！住手！這樣改會害死前端喔！」
2. Visual Diff：別再用肉眼找不同
傳統的 Code Review 都是看 Git 的文字比對 (Diff)，在一堆 YAML 縮排中很難看出結構變化。 Swagger (SwaggerHub) 提供了 Visual Diff (視覺化比對) 功能。它會並排顯示兩個版本的 API 文件，並用顏色標示出：
-
🟢 綠色：新增的 Endpoint。
-
🔴 紅色：被刪除的危險區域。
-
🟡 黃色：被修改的定義。
技術主管在審核 API 變更時，不需要懂複雜的程式碼，只要看顏色就能秒懂這次改版有沒有風險。
API Versioning：舊的不去，新的也能來
如果業務需求真的必須刪除那個欄位怎麼辦？這時候你需要的是 API Versioning (版本策略)。
在 Swagger (SwaggerHub) 中，我們可以輕鬆管理多個版本：
-
v1.0 (Locked)：標記為「已發布」，供現有 App 使用。這份 Spec 是唯讀的，確保沒有人能偷偷改壞它。
-
v2.0 (Draft)：從 v1.0 複製 (Fork) 出來的新版本。在這裡，你可以大膽地刪除
userAge，進行破壞性重構。
前端團隊可以看著 v2.0 的文件開發新版 App，而舊版 App 繼續安穩地呼叫 v1.0 的接口。直到所有舊用戶都更新 App 後，我們再將 v1.0 下架 (Deprecate)。
這就是 「平行版本管理」 的真諦。
結論：從「人治」走向「法治」
很多團隊的 API 災難，都是源於「我以為這個改動很小」。
導入 SmartBear Swagger (SwaggerHub) 的價值在於，它將「檢查 Breaking Change」這件事，從依賴工程師的細心，轉變為依賴系統的自動化。
別讓一次小小的 Commit，成為毀掉週末假期的兇手。善用版本控管與自動檢測，讓你的 API 迭代既快速又安全。
💡 下一步預告
解決了版本衝突，我們的 API 定義已經很安全了。但如果公司有 50 個微服務，每個服務都自己定義了一套「使用者模型 (User Model)」，那豈不是另一種混亂？ 下一次，我們要來探討如何利用 「Domain 模組化設計」，像玩樂高一樣組裝你的 API，達成真正的企業級標準化。
想要了解更多？趕快和我們聯絡！