如何設計能撐住產品成長的 API 契約

好的 API 契約之所以能長期成功，並不是因為它在第一天就被設計得完美無缺，而是因為它保留了足夠的成長空間，不會強迫使用者不停投入遷移成本。

當產品逐漸成熟，API 往往不再只服務最初那一種使用情境。原本只給單一前端、單一內部服務或單一整合夥伴使用的契約，最後會變成整個團隊共享的基礎設施。通常也就是在這個時候，那些原本看起來無傷大雅的小不一致，開始變得昂貴。

先為相容性最佳化

我傾向把 breaking change 視為一個維運事件，而不只是一次程式碼修改。這種心態會提早影響設計決策：它會鼓勵你用加法演進、明確預設值，以及清楚的淘汰路徑，而不是突然用「順手整理一下」的名義破壞 API。

最容易長期共存的契約通常有三個共同特徵：

• 它們會明確表達哪些欄位是可選的
• 它們用穩定的欄位名稱描述行為
• 它們不會讓同一個 endpoint 同時背負多種彼此不相容的語意

把傳輸形狀和領域語言分開

我很常看到的一個問題，是把內部命名方式或資料庫結構直接洩漏到對外契約。短期看起來可能讓交付更快，但它會顯著提高未來重構的成本。

傳輸模型應該是經過刻意設計的。如果某個欄位名稱之所以存在，只是因為資料表欄位剛好叫這個名字，那通常值得慢下來想一下：客戶端真的有必要承擔這個命名嗎？

少做版本切換，多做溝通

我不會每次 response 有變化就立刻開一個全新版本號。對很多團隊來說，只要有紀律地做加法式修改，再搭配清楚記錄的淘汰流程，通常就已經夠了。版本控制很有用，但它不是相容性思維的替代品。

更重要的是讓契約變更能被看見：

• 發布反映真實使用情境的範例
• 在移除行為前先掌握消費方
• 清楚記錄淘汰期間
• 在整合風險高的地方加入契約測試

對分頁、篩選與錯誤格式保持明確

這些通常是 API 使用者最容易建立假設的地方。如果分頁 metadata 不一致，或不同 endpoint 的篩選行為各說各話，使用方就會開始實作脆弱的繞路邏輯。

比起把單一 endpoint 打磨得很漂亮，我更願意花時間把 API 的共同基礎建設標準化。真正讓整個系統更容易整合的，往往是那些看起來最無聊的部分。

把範例當成契約的一部分

參考範例能防止模糊空間，這是單靠文字敘述往往做不到的。它也能幫助 reviewer 在問題進到正式環境前，就先發現契約是否已經不知不覺地漂移。

即使是一個簡短的 payload 範例，也能做很多事：

{
  "data": [
    {
      "id": "svc_1024",
      "name": "edge-cache",
      "status": "healthy"
    }
  ],
  "meta": {
    "next_cursor": "eyJwYWdlIjoyfQ=="
  }
}

穩定契約能降低協作成本

設計良好的 API 真正的價值，不是優雅，而是能降低產品、後端、維運與整合團隊之間的協作負擔。穩定的契約意味著更少的緊急澄清、更少的 rollout 阻塞，以及在服務各自演進時仍然保有信心。

這通常就是「一個只是能用的 API」和「一個在組織持續變化下仍然好用的 API」之間的差別。