使用ASP.NET Core 3.x 構建 RESTful API - 3.3 狀態碼、錯誤/故障、ProblemDetails

HTTP狀態碼

HTTP狀態碼會告訴API的消費者如下事情： 

• 請求是否執行成功了 

• 若是請求失敗了，那麼誰爲它負責 

 

HTTP的狀態碼有不少，可是Web API不必定須要支持全部的狀態碼。HTTP狀態碼一共分爲5個級別： 

• 1xx，屬於信息性的狀態碼。Web API並不使用1xx的狀態碼。 

• 2xx，意味着請求執行的很成功。 

  • 200 - Ok，表示請求成功； 

  • 201 - Created，請求成功並建立了資源； 

  • 204 - No Content，請求成功，可是不該該返回任何東西，例如刪除操做。 

• 3xx，用於跳轉。例如告訴搜素引擎，某個頁面的網址已經永久的改變了。絕大多數的Web API都不須要使用這類狀態碼。 

• 4xx，客戶端錯誤： 

  • 400 - Bad Request，表示API消費者發送到服務器的請求是有錯誤的； 

  • 401 - Unauthorized，表示沒有提供受權信息或者提供的受權信息不正確； 

  • 403 - Forbidden，表示身份認證已經成功，可是已認證的用戶卻沒法訪問請求的資源； 

  • 404 - Not Found，表示請求的資源不存在； 

  • 405 - Method not allowed，當嘗試發送請求到資源的時候，使用了不被支持的HTTP方法時，就會返回405狀態碼； 

  • 406 - Not acceptable，這表示API消費者請求的表述格式並不被Web API所支持，而且API不會提供默認的表述格式。例如請求的媒體類型是application/xml，可是Web API僅支持application/json類型，而且API不會將application/json做爲默認格式提供； 

  • 409 - Conflict，表示請求與服務器當前狀態衝突。一般指更新資源時發生的衝突，例如，當你編輯某個資源的時候，該資源在服務器上又進行了更新，因此你編輯的資源版本和服務器的不一致。固然有時候也用來表示你想要建立的資源在服務器上已經存在了。它就是用來處理併發問題的狀態碼。  

  • 415 - Unsupported media type，與406正好相反，有一些請求必須帶着數據發往服務器，這些數據都屬於特定的媒體類型，若是API不支持該媒體類型格式，415就會被返回。 

  • 422 - Unprocessable entity，它是HTTP擴展協議的一部分。它說明服務器已經懂得了實體的Content Type，也就是說415狀態碼確定不合適；此外，實體的語法也沒有問題，因此400也不合適。可是服務器仍然沒法處理這個實體數據，這時就能夠返回422。因此它一般是用來表示語意上有錯誤，一般就表示實體驗證的錯誤。 

• 5xx，服務器錯誤： 

• 500 - Internal server error，表示服務器出現了錯誤，客戶端無能爲力，只能之後再試試了。 

 

錯誤和故障

系統時不時的會出現一些問題，這些問題能夠劃分爲兩類：錯誤和故障。 

 

錯誤 Errors 

錯誤一般是由API的消費者引發的。API消費者請求時傳遞的數據是不合理的，這時API就會正常的將其拒絕。例如，請求的憑證是不合理的，或者請求的參數不合理等等。  

這些就是HTTP  4xx錯誤。  

錯誤並不會影響API的可用性。 

 

故障 Faults 

故障是指，針對一個合理的請求，API沒法返回它的響應。 換句話說就是API引發的問題。 

這些是HTTP 5xx錯誤。 

故障確實會對API總體的可用性形成影響。 

 

ProblemDetails

當ASP.NET Core 大約在 2.1 版本的時候，它引入了 ProblemDetails。ProblemDetails是基於 RFC7807 這個規範，目的是讓 HTTP 響應能夠攜帶錯誤的詳細信息，而不是隻返回一個錯誤的狀態碼。 

在 ASP.NET Core 2.2的時候，若是Controller使用了 [ApiController] 這個屬性，那麼 ProblemDetails 就是客戶端錯誤碼的標準響應。 

例如，當返回類型爲 IActionResult 的方法返回客戶端錯誤狀態碼的時候（4xx），同時還會返回一個body，這個 body 就是 ProblemDetails。 這個結果裏還會包含着一個相關的ID，使用這個ID，就能夠把錯誤和相應的請求日誌關聯起來。 

 

關於ProblemDetails這個類，能夠查看：官方文檔。 

 

爲了使用ProblemDetails？ 

• 須要爲應用程序定義一個通用的錯誤顯示格式； 

• 不少時候,只返回HTTP狀態碼並不能表達和傳遞出足夠的信息。 

 

在ASP.NET Core 3.x裏面，一樣也使用了 ProblemDetails。 

看一個返回404的例子： 

這是一個Get請求，可是並無找到該資源，返回的狀態碼是404，而響應的body就是 ProblemDetails。 

值得注意的是，這個響應的 Content-Type 是 application/problem+json：