使用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：