HTTP 方法與狀態碼 — 讓 API 說人話

在設計或串接 API 時，我們最常打交道的就是 HTTP 方法（Methods）和狀態碼（Status Codes）。正確使用它們，能讓你的 API 更語意化、更易於維護，就像兩個人在用標準的語言溝通，而不是雞同鴨講。

HTTP 方法：動作是什麼？

最常見的方法對應到資料庫操作的 CRUD（PUT 與 PATCH 都對應「Update」，所以底下會介紹五種方法）：

GET：讀取資料

• 用途：取得資源。
• 特性：安全（Safe） 且 冪等（Idempotent）。意思是它不會修改伺服器資料，且執行多次的結果都一樣。
• 例子：GET /users/123（取得 ID 為 123 的使用者資料）

POST：新增資料

• 用途：建立新資源。
• 特性：不冪等。執行兩次會建立兩筆資料。
• 例子：POST /users（建立一個新使用者）

PUT：更新資料（整筆替換）

• 用途：用新的資料完全覆蓋舊資料。
• 特性：冪等。
• 例子：PUT /users/123（更新使用者 123 的所有資料，沒傳的欄位會被視為刪除或設為 null）

PATCH：更新資料（部分修改）

• 用途：只修改部分欄位。
• 特性：通常視為不冪等（但在實務上常設計為冪等）。
• 例子：PATCH /users/123（只修改使用者 123 的 email）

DELETE：刪除資料

• 用途：移除資源。
• 特性：冪等。刪除一次和刪除多次的結果是一樣的（資源都不見了）。
• 例子：DELETE /users/123（刪除使用者 123）

HTTP 狀態碼：結果如何？

狀態碼分為五大類：

1xx：資訊回應

• 100 Continue：伺服器已收到請求的標頭，客戶端應繼續發送主體。

2xx：成功（Success）

• 200 OK：最常見的成功回應。
• 201 Created：請求成功且建立了新資源。通常用於 POST 請求的回應。
• 204 No Content：請求成功，但回應沒有內容。通常用於 DELETE 請求。

3xx：重新導向（Redirection）

• 301 Moved Permanently：資源已永久移動到新位置。搜尋引擎會更新索引。
• 302 Found：資源暫時移動到新位置。
• 304 Not Modified：快取未過期，資源沒變更，可直接使用快取。這對節省流量非常重要。

4xx：客戶端錯誤（Client Error）

• 400 Bad Request：請求格式錯誤，伺服器看不懂。
• 401 Unauthorized：未認證。你沒有登入或 Token 無效。
• 403 Forbidden：禁止存取。你登入了，但權限不足（例如一般會員想看管理者頁面）。
• 404 Not Found：資源不存在。
• 418 I’m a teapot：愚人節玩笑定義的狀態碼，意思是「你不能用茶壺來泡咖啡」，偶爾會在某些 IoT 設備或彩蛋中看到它。
• 429 Too Many Requests：請求次數過多，被限流了。

5xx：伺服器錯誤（Server Error）

• 500 Internal Server Error：伺服器壞了，或是程式碼噴錯了。通常是後端要修這個 bug。
• 502 Bad Gateway：作為網關或代理的伺服器，從上游伺服器收到無效回應。常見於 Nginx 設定錯誤。
• 503 Service Unavailable：伺服器暫時無法處理請求（過載或維護中）。
• 504 Gateway Timeout：網關等不到上游伺服器的回應。

為什麼要區分這麼細？

其實你可以永遠都回傳 200 OK，然後在 JSON 裡用 success: false 來表示錯誤。但這樣做有幾個缺點：

1. 監控困難：運維系統通常只監控 HTTP 狀態碼。如果你都回 200，它會以為系統很健康，實際上可能全是錯誤。
2. 不符合語意：瀏覽器和快取伺服器依賴狀態碼來決定行為（例如看到 304 就讀快取）。
3. 溝通成本高：串接方需要去讀你的文件才知道 error_code: 999 是什麼意思，而不像 404 是通用語言。

結語

設計良好的 API 就像寫作，HTTP 方法是動詞，URL 是名詞，狀態碼是語氣。掌握這些基礎，能讓你寫出更優雅、更專業的介面。

站內相關文章：

• DNS 深度解析