API 設計中 HTTP 狀態碼的終極參考

在 Web 開發和 API 設計領域，HTTP 狀態代碼在客戶端和伺服器之間傳達請求結果方面發揮著至關重要的作用。這些程式碼提供了一種標準化的方式來指示在處理 HTTP 請求期間發生的特定條件、成功或錯誤。了解這些狀態程式碼對於開發人員來說至關重要，因為它有助於偵錯、錯誤處理和創建更強大的應用程式。

1. 1xx 訊息

這些狀態代碼表示臨時回應。它們在實踐中很少使用，但在某些情況下會很有幫助。

• 100 Continue：伺服器已收到請求標頭，客戶端應繼續傳送請求正文。
• 101 切換協議：請求者要求伺服器切換協議，且伺服器已同意這樣做。

2. 2xx 成功

這些狀態代碼表示客戶端的請求已成功接收、理解並接受。

• 200 OK：請求成功，回應中包含請求的資料或結果。
  • 範例：檢索使用者的個人資料資訊。
• 201 Created：請求成功，建立了新資源。
  • 範例：建立新使用者帳戶或發布新部落格條目。
• 204 No Content：伺服器成功處理請求，但未傳回任何內容。
  • 範例：更新不需要回應正文的使用者設定。
• 206 部分內容：由於客戶端發送的範圍標頭，伺服器僅提供部分資源。
  • 範例：串流影片內容或分塊下載大檔案。

3. 3xx重定向

這些狀態代碼表明用戶代理需要採取進一步的操作來滿足請求。

• 301 Moved Permanently：要求的資源已永久移至新的 URL。
• 302 Found：要求的資源暫時駐留在不同的 URL 下。
• 304 Not Modified：表示資源自請求頭指定的版本以來尚未被修改。

4. 4xx客戶端錯誤

這些狀態代碼適用於客戶端似乎犯了錯誤的情況。

• 400 Bad Request：由於語法無效或輸入錯誤，伺服器無法處理請求。

  • 範例：在請求正文中傳送格式錯誤的 JSON。
  • 用法：當請求本身格式錯誤或包含無效參數時使用。

• 401 Unauthorized：請求需要使用者驗證。

  • 範例：在不提供有效憑證的情況下嘗試存取受保護的 API 端點。
  • 用途：需要身份驗證且未提供或無效時使用。

• 403 Forbidden：伺服器理解請求，但拒絕授權。

  • 範例：使用者嘗試存取僅限管理員的功能。
  • 用法：當使用者經過身份驗證但沒有要求操作的權限時使用。

• 404 Not Found：在伺服器上找不到要求的資源。

  • 範例：嘗試檢索已刪除的使用者設定檔。
  • 用法：當請求的資源不存在時使用。

• 405 Method Not allowed：請求 URI 識別的資源不允許使用請求中指定的方法。

  • 範例：向僅接受 GET 請求的端點發送 POST 請求。

• 409 衝突：由於與資源的當前狀態衝突，無法處理請求。

  • 範例：嘗試使用系統中已存在的電子郵件建立使用者。
  • 用途：與資源目前狀態衝突時使用，例如重複條目。

• 422 無法處理的實體：伺服器理解請求的內容類型和語法，但無法處理其中包含的指令。

  • 範例：提交包含無效資料的表單，導致伺服器端驗證失敗。
  • 用途：用於請求語法正確但資料語意不正確的驗證錯誤。

• 429 太多請求：使用者在給定時間內發送了太多請求（「速率限制」）。

  • 範例：實作 API 速率限制以防止濫用。

5. 5xx伺服器錯誤

這些狀態代碼表示伺服器知道它遇到錯誤或無法執行請求的情況。

• 500 內部伺服器錯誤：一般錯誤訊息，指示伺服器遇到意外狀況，導致其無法滿足要求。

  • 範例：伺服器端程式碼中發生未處理的異常。

• 501 Not Implemented：伺服器不支援滿足請求所需的功能。

  • 範例：使用伺服器無法辨識的新 HTTP 方法。

• 502 Bad Gateway：伺服器在充當網關或代理時，從上游伺服器收到無效回應。

  • 範例：反向代理伺服器無法連線到來源伺服器。

• 503 Service Unavailable：伺服器由於暫時超載或維護，目前無法處理請求。

  • 範例：伺服器正在進行定期維護或流量較高。

• 504 網關逾時：伺服器在充當網關或代理時，沒有收到上游伺服器的及時回應。

  • 範例：等待第三方API回應逾時。

使用 HTTP 狀態碼的最佳實踐

1. 具體：使用適用於具體情況的最具體的狀態代碼。這有助於客戶準確地了解發生了什麼以及如何應對。

2. 一致使用：保持 API 中狀態碼使用方式的一致性。這使開發人員可以更輕鬆地使用您的 API。

3. 提供其他資訊：除了狀態代碼之外，還應在適當的情況下在回應正文中包含詳細的錯誤訊息。這可以幫助調試並改善開發人員體驗。

4. 安全注意事項：請謹慎，不要在錯誤回應中洩露太多信息，尤其是 4xx 和 5xx 錯誤。避免暴露有關係統架構或實現的敏感細節。

5. 文件：清楚記錄您的 API 使用哪些狀態代碼以及在什麼情況下使用。這有助於 API 用戶了解如何解釋和處理不同的回應。

透過理解並正確實作 HTTP 狀態代碼，開發人員可以創建更健壯、清晰且用戶友好的 API 和 Web 應用程式。這些程式碼可作為客戶端和伺服器之間的重要通訊工具，有助於簡化錯誤處理並提高整體系統可靠性。

以上是API 設計中 HTTP 狀態碼的終極參考的詳細內容。更多資訊請關注PHP中文網其他相關文章！