我最近在處理官網和系統的串接時，最常花時間的不是寫 fetch 或打 token，而是把資料邊界講清楚。API 真正麻煩的地方，通常在欄位、狀態和失敗流程，不在呼叫本身。
如果一開始只問「endpoint 在哪裡」，很容易做到一半才發現欄位意義不一致、錯誤格式沒定、重送會重複建資料。這些都不是前端或後端單方面能補掉的問題。
這篇核心結論
串 API 前先把資料邊界畫清楚，後面才不會一直用程式碼補合約沒講清楚的洞。
先確認輸入和輸出，不要先把程式接上去
我會先問：誰送資料、誰接資料、欄位來源是哪裡、哪些欄位必填、哪些欄位可以缺。這些看起來很基本，但只要一個欄位含義不清，UI、後台和報表都會被影響。
例如同樣叫 status，有的系統代表付款狀態，有的代表審核狀態，有的代表任務處理狀態。名字一樣，不代表邊界一樣。
失敗情境比成功情境更值得先講
成功情境通常只有一條路：送出、收到、完成。但真實系統會遇到逾時、重複送出、第三方回錯、資料不完整、權限不足、使用者中途離開。這些如果沒有先定，開發時就會一直補例外。
| 情境 | 要先定義 | 沒定義會怎樣 |
|---|---|---|
| 逾時 | 前端顯示、後端是否重試 | 使用者不知道成功或失敗 |
| 重複送出 | idempotency key 或防重規則 | 重複建單、重複扣款或重複通知 |
| 權限不足 | 錯誤碼與導回路徑 | 畫面只剩 generic error |
| 資料缺漏 | 哪一層驗證、誰負責補 | 前後端互相猜欄位規則 |
我現在串 API 會先畫的不是流程圖，而是邊界表
只要把誰送什麼、誰回什麼、哪裡可能失敗、失敗了怎麼補救先寫清楚，後面的開發和測試都會快很多。這也是為什麼我現在做 API integration，第一步常常不是進 IDE，而是先整理欄位。
邊界表最少包含
- 欄位名稱、型別、必填與範例值。
- 成功回應與每種錯誤回應格式。
- 重試、取消、逾時和重複送出的處理方式。
- 資料來源、資料擁有者和修復責任。
等這些規則穩了之後，再去接 UI、接後台、接通知流程，整條路才不會一路重拆。
常見 FAQ
FAQ
- API 文件已經有了，還需要邊界表嗎？
需要。API 文件通常描述接口，但邊界表會補上實際產品流程中的責任、錯誤和重試規則。 - 小專案也要這麼做嗎？
可以簡化，但至少要寫清楚欄位、錯誤和重複送出規則，避免後期重工。 - 誰該負責資料邊界？
通常需要前端、後端和產品一起定，因為它同時影響畫面、資料庫和使用者流程。
結論
API 串接不是把資料接起來而已，而是把責任邊界接清楚。邊界先定好，程式才不用一直替模糊規則擦屁股。
