API 介接

白話文說明

API（應用程式介面） 就是兩個系統之間「講好的溝通方式」。前端想要資料，不能直接闖進後端的廚房，而是走 API 這個櫃台：照規定的格式提出請求，後端照規定的格式回覆。

好的 API 有清楚的契約：請求要帶什麼、回應長什麼樣、出錯時回什麼代碼。契約清楚，前後端就能各自獨立開發，也方便 AI 幫你產生正確的串接程式。

架構圖

運作流程

好契約與壞契約

一個 API 好不好串接，差別就在契約。

• 好契約清楚（請求與回應長什麼樣都寫明）、穩定（不會在你沒注意時偷偷改掉）、有文件（每個欄位代表什麼都查得到）、有版本（新版走 /v2/，舊的 /v1/ 照常運作）。
• 壞契約毫無預警就變動，把依賴它的東西全弄壞；還會洩漏內部細節，例如直接吐出資料庫欄位或錯誤堆疊；又沒有文件，只能靠一再試誤去摸清它的行為。

重點整理

• API＝系統間「講好的溝通窗口」。
• 重點在契約：請求格式、回應格式、錯誤代碼。
• 契約變更要做版本（例如 /v1/、/v2/），避免一改全壞。