約 2 分鐘閱讀
HTTP 方法與狀態碼 — 讓 API 說人話
在設計或串接 API 時，我們最常打交道的就是 HTTP 方法 (Methods) 和狀態碼 (Status Codes)。正確使用它們，能讓你的 API 更語意化、更易於維護，就像兩個人在用標準的語言溝通，而不是雞同鴨講。
HTTP 方法：動作是什麼？
最常見的四種方法對應到資料庫操作的 CRUD：
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：資源不存在。
- 429 Too Many Requests：請求次數過多，被限流了。
418 I’m a teapot (我是個茶壺)
這是一個愚人節玩笑定義的狀態碼，意思是「你不能用茶壺來泡咖啡」。但在某些 IoT 設備或彩蛋中會看到它。
5xx：伺服器錯誤 (Server Error)
- 500 Internal Server Error：伺服器壞了，或是程式碼噴錯了。通常是後端要修這個 bug。
- 502 Bad Gateway：作為網關或代理的伺服器，從上游伺服器收到無效回應。常見於 Nginx 設定錯誤。
- 503 Service Unavailable：伺服器暫時無法處理請求 (過載或維護中)。
- 504 Gateway Timeout：網關等不到上游伺服器的回應。
為什麼要區分這麼細？
其實你可以永遠都回傳 200 OK，然後在 JSON 裡用 success: false 來表示錯誤。但這樣做有幾個缺點：
- 監控困難：運維系統通常只監控 HTTP 狀態碼。如果你都回 200，它會以為系統很健康，實際上可能全是錯誤。
- 不符合語意：瀏覽器和快取伺服器依賴狀態碼來決定行為 (例如看到 304 就讀快取)。
- 溝通成本高：串接方需要去讀你的文件才知道
error_code: 999是什麼意思，而不像404是通用語言。
結語
設計良好的 API 就像寫作，HTTP 方法是動詞，URL 是名詞，狀態碼是語氣。掌握這些基礎，能讓你寫出更優雅、更專業的介面。
站內相關文章：