ADP
API Design PrincipleBETA

繁體中文

English

繁體中文

English

Appearance

[ADP-365] 自定義狀態碼 ​

指導方針 ​

避免自定義狀態碼 ​

  • 禁止(MUST NOT)創建自定義 HTTP 狀態碼。
  • 應該(SHOULD)使用 RFC 7231/RFC 9110 和其他相關 RFC 中定義的標準 HTTP 狀態碼。

使用問題詳情 ​

  • 當標準狀態碼不足以描述時，應該使用問題詳情(RFC 9457)來提供更具體的錯誤資訊。
  • 可以定義自定義問題類型來表示特定應用程序的錯誤。有關自定義問題類型的指導，請參見 ADP-403: 問題類型設計。

示例 ​

http
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://example.com/probs/invalid-user-input",
  "title": "無效的用戶輸入",
  "status": 400,
  "detail": "提供的電子郵件地址格式無效。",
  "instance": "/users/create"
}

文件 ​

  • 必須(MUST)在 API 文件中記錄所有使用的 HTTP 狀態碼及其相關的問題詳情。
  • 應該(SHOULD)在 API 文件中提供錯誤回應的示例。
  • 應該(SHOULD)在公用的 OpenAPI problems.yaml 中加入錯誤回應方便共用，請參閱 ADP-767。

理由 ​

自定義狀態碼可能導致互操作性問題，並使 API 消費者感到困惑。通過使用標準狀態碼和問題詳情，我們可以確保更好的兼容性，並提供一種更標準化的方式來傳達錯誤和異常情況。

參考資料 ​