知識庫 / REST RSS 訂閱

1. 概述

REST 是一種無狀態架構，客户端可以訪問和操作服務器上的資源。通常，RESTful 服務使用 HTTP 來宣佈它們管理的一組資源，並提供一個 API，允許客户端獲取或修改這些資源的當前狀態。

在本教程中，我們將學習處理 REST API 錯誤的一些最佳實踐，包括為用户提供相關信息的有用方法，來自大型網站的示例以及使用示例 Spring REST 應用程序的實際實現。

2. HTTP 狀態碼

當客户端向 HTTP 服務器發送請求，且服務器成功接收到該請求時，服務器必須通知客户端請求是否成功處理或未處理。

HTTP 通過五類狀態碼來實現這一點：

• 100-級別（指示性） – 服務器確認請求
• 200-級別（成功） – 服務器已按照預期完成請求
• 300-級別（重定向） – 客户端需要執行進一步操作以完成請求
• 400-級別（客户端錯誤） – 客户端發送了無效請求
• 500-級別（服務器錯誤） – 由於服務器端錯誤，未能滿足有效的請求

根據響應代碼，客户端可以推斷出特定請求的結果。

3. 處理錯誤

提供適當的狀態碼是處理錯誤的最初步驟。此外，我們可能還需要在響應體中提供更多信息。

3.1. 基本響應

處理錯誤的最簡單方法是使用適當的狀態碼進行響應。

以下是一些常見的響應碼：

• 400 Bad Request – 客户端發送了無效請求，例如缺少必需的請求主體或參數。
• 401 Unauthorized – 客户端未成功與服務器進行身份驗證。
• 403 Forbidden – 客户端已進行身份驗證，但沒有權限訪問請求的資源。
• 404 Not Found – 請求的資源不存在。
• 412 Precondition Failed – 請求頭字段中的一個或多個條件評估結果為 false。
• 500 Internal Server Error – 服務器在處理請求時發生了通用錯誤。
• 503 Service Unavailable – 請求的服務不可用。

雖然這些代碼是基礎的，但它們允許客户端了解發生的錯誤的大致性質。例如，如果收到 403 錯誤，我們知道我們缺乏訪問請求資源的權限。然而，在許多情況下，我們需要在響應中提供補充信息。

500 錯誤表明在處理請求時，服務器上發生了某些問題或異常。通常，此內部錯誤不屬於我們的客户端業務。

因此，為了儘量減少這些響應對客户端的影響，我們應該盡力處理或捕獲內部錯誤，並在可能的情況下使用其他適當的狀態碼。

例如，如果由於請求的資源不存在而發生異常，我們應該將其暴露為 404 錯誤，而不是 500 錯誤。

這並不意味着 500 永遠不應該返回，只是它應該用於意外條件——例如服務中斷——導致服務器無法執行請求時。

3.2. 默認 Spring 錯誤響應

這些原則過於普遍，Spring 已經將其編碼到默認的錯誤處理機制中。

為了説明，假設我們有一個 簡單的 Spring REST 應用，該應用管理書籍，並提供一個端點來根據 ID 檢索書籍：

curl -X GET -H "Accept: application/json" http://localhost:8082/spring-rest/api/book/1

如果不存在 ID 為 1 的書籍，我們期望我們的控制器會拋出 BookNotFoundException。

對該端點執行 GET 請求，我們看到該異常被拋出，並且這是響應體：

{
    "timestamp":"2019-09-16T22:14:45.624+0000",
    "status":500,
    "error":"Internal Server Error",
    "message":"No message available",
    "path":"/api/book/1"
}

請注意，此默認錯誤處理程序包含錯誤發生的時間戳、HTTP 狀態碼、標題（error 字段）、如果啓用了默認錯誤中的消息則消息（默認情況下為空）以及錯誤發生的 URL 路徑。

這些字段為客户端或開發人員提供信息，以幫助他們解決問題，並且也構成標準錯誤處理機制中的幾個字段。

請注意，Spring 在我們的 BookNotFoundException 被拋出時，會自動返回 HTTP 狀態碼 500。雖然某些 API 會返回 500 狀態碼或其他通用狀態碼，正如我們將在 Facebook 和 Twitter API 中看到的那樣，為了簡化起見，儘可能使用最具體的錯誤代碼。

在我們的示例中，我們可以添加一個 @ControllerAdvice，以便當 BookNotFoundException 被拋出時，我們的 API 返回 404 狀態碼，以表示 未找到，而不是 500 內部服務器錯誤。

3.3. 更詳細的響應

如上所示的 Spring 示例中，有時狀態碼本身不足以展示錯誤的具體信息。當需要時，我們可以使用響應體向客户端提供額外信息。

在提供詳細響應時，我們應該包含：

• 錯誤 – 唯一的錯誤標識符
• 消息 – 簡短的人類可讀的消息
• 詳細信息 – 錯誤的更詳細的解釋

例如，如果客户端發送帶有錯誤的憑據的請求，我們可以發送以下 401 響應：

{
    "error": "auth-0001",
    "message": "Incorrect username and password",
    "detail": "Ensure that the username and password included in the request are correct"
}

錯誤字段不應與響應代碼匹配。相反，它應是特定於我們應用程序的唯一錯誤代碼。通常，錯誤字段沒有約定，除了它必須是唯一的。

通常，此字段僅包含字母數字字符和連接字符，例如短劃線或下劃線。例如，0001、auth-0001和incorrect-user-pass是唯一錯誤代碼的典範示例。

通常，請求體中的消息部分被認為是用户界面上可呈現的。因此，如果支持國際化，我們應將此標題翻譯。因此，如果客户端發送帶有與法語相對應的Accept-Language標頭請求，則標題值應翻譯為法語。

{
    "error": "auth-0001",
    "message": "Incorrect username and password",
    "detail": "Ensure that the username and password included in the request are correct",
    "help": "https://example.com/help/error/auth-0001"
}

{
    "errors": [
        {
            "error": "auth-0001",
            "message": "Incorrect username and password",
            "detail": "Ensure that the username and password included in the request are correct",
            "help": "https://example.com/help/error/auth-0001"
        },
        ...
    ]
}

{
    "type": "/errors/incorrect-user-pass",
    "title": "Incorrect username or password.",
    "status": 401,
    "detail": "Authentication failed due to incorrect username or password.",
    "instance": "/login/log/abc123"
}

curl -X GET https://api.twitter.com/1.1/statuses/update.json?include_entities=true

{
    "errors": [
        {
            "code":215,
            "message":"Bad Authentication data."
        }
    ]
}

curl -X GET https://graph.facebook.com/oauth/access_token?client_id=foo&client_secret=bar&grant_type=baz

{
    "error": {
        "message": "Missing redirect_uri parameter.",
        "type": "OAuthException",
        "code": 191,
        "fbtrace_id": "AWswcVwbcqfgrSgjG80MtqJ"
    }
}