錯誤處理 ¶

當處理 RESTful API 請求時，如果使用者請求中存在錯誤，或者伺服器上發生意外情況，您可以簡單地拋出異常，以通知使用者發生了錯誤。如果您可以確定錯誤的原因（例如，請求的資源不存在），則應考慮拋出帶有正確 HTTP 狀態碼的異常（例如，yii\web\NotFoundHttpException 代表 404 狀態碼）。Yii 將發送帶有相應 HTTP 狀態碼和文字的回應。Yii 還將在回應主體中包含異常的序列化表示形式。例如

HTTP/1.1 404 Not Found
Date: Sun, 02 Mar 2014 05:31:43 GMT
Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8

{
    "name": "Not Found Exception",
    "message": "The requested resource was not found.",
    "code": 0,
    "status": 404
}

以下列表總結了 Yii REST 框架使用的 HTTP 狀態碼

• 200：OK。一切都如預期般運作。
• 201：已成功創建資源以回應 POST 請求。Location 標頭包含指向新創建資源的 URL。
• 204：請求已成功處理，並且回應不包含任何主體內容（例如 DELETE 請求）。
• 304：資源未修改。您可以使用快取版本。
• 400：錯誤請求。這可能是由使用者的各種操作引起的，例如在請求主體中提供無效的 JSON 資料、提供無效的操作參數等。
• 401：身份驗證失敗。
• 403：經過身份驗證的使用者無權訪問指定的 API 端點。
• 404：請求的資源不存在。
• 405：不允許的方法。請檢查 Allow 標頭以獲取允許的 HTTP 方法。
• 415：不支援的媒體類型。請求的內容類型或版本號無效。
• 422：資料驗證失敗（例如，回應 POST 請求）。請檢查回應主體以獲取詳細的錯誤訊息。
• 429：請求過多。由於速率限制，請求被拒絕。
• 500：內部伺服器錯誤。這可能是由內部程式錯誤引起的。

自訂錯誤回應 ¶

有時您可能想要自訂預設錯誤回應格式。例如，您可能希望始終使用 200 作為 HTTP 狀態，並將實際的 HTTP 狀態碼作為回應中 JSON 結構的一部分包含在內，而不是依賴於使用不同的 HTTP 狀態來指示不同的錯誤，如下所示，

HTTP/1.1 200 OK
Date: Sun, 02 Mar 2014 05:31:43 GMT
Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8

{
    "success": false,
    "data": {
        "name": "Not Found Exception",
        "message": "The requested resource was not found.",
        "code": 0,
        "status": 404
    }
}

為了實現此目標，您可以回應應用程式配置中 response 組件的 beforeSend 事件

return [
    // ...
    'components' => [
        'response' => [
            'class' => 'yii\web\Response',
            'on beforeSend' => function ($event) {
                $response = $event->sender;
                if ($response->data !== null && Yii::$app->request->get('suppress_response_code')) {
                    $response->data = [
                        'success' => $response->isSuccessful,
                        'data' => $response->data,
                    ];
                    $response->statusCode = 200;
                }
            },
        ],
    ],
];

當 suppress_response_code 作為 GET 參數傳遞時，以上程式碼將重新格式化回應（對於成功和失敗的回應），如所解釋的那樣。