[ADP-403] 問題類型設計

核心原則

1. URI 參考：必須(MUST)是人類可讀的 URI reference。
2. 相對 URI：當不確定問題發布位置或是否發布時，可(MAY)使用相對 URI reference。

設計流程

1. 檢視現有的 HTTP 狀態碼，參考 ADP-200。
2. 對於完全匹配的情況，使用 type: about:blank或該 HTTP 狀態碼的 URI reference 轉換(如：/problems/not-found)。
3. 利用 detail 欄位提供修正錯誤的方法。
4. 如果沒有匹配的狀態，應查閱預定義的問題類型列表。
5. 必要時提出新類型，確保它們足夠通用。
6. 使用 errors 欄位描述多個錯誤。

子類型設計提案

在 RFC 9457 的提案中，對於類型(type)的要求是必須足夠通用，但有時候我們可能需要更為詳細的子類型，以便客戶端能夠進行對應處理。顯然，在這種情況下我們不應該使用 title 或 detail 來進行對照。因此，這裡我們提出了一個新的欄位設計：子類型，也稱為額外類型。

其設計理念是，最終可以通過將問題域(problem domain) + 问题類型(problem type) + / + 额外類型(problem extra type)組合成一個指涉到該子類型的 URI 參考，例如：https://apidoc.alive.dev/problems/not-found/user-not-found。

• 可以(MAY)引入 extraType 欄位以增強描述

  {
    "type": "https://example.com/problems/authentication-error",
    "title": "Authentication Error",
    "extraType": "request-timeout-to-third-party",
    "status": 409,
    "detail": "Your session has expired due to JWT",
    "errors": []
  }

• extraType 應(SHOULD)與錯誤詳情一對一對應

• extraType 可(MAY)是產品特定的

RFC 9457 合規指南

1. 問題類型必須(MUST)是通用的，而非特定產品的。
2. 應(SHOULD)最大化重用現有問題類型。
3. 當 HTTP 狀態碼足夠時使用 about:blank。查閱ADP-402
4. 查閱ADP-406 以取得更多類型的範例。

參考資料

• 問題詳情註冊表
• RFC 9457