使用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:
最新文章
- C#基础-邮件发送
- MySQL备份还原——mysqldump工具介绍
- sql语句注意事项
- 减小服务器负担,Apache启用mod_expires模块
- [置顶] TortoiseGit和msysGit安装及使用笔记(windows下使用上传数据到GitHub)
- spring 4.2.0后jdbcTemplate中不用queryForLong了(之系统升级发现)
- SVN常见错误和版本冲突解决
- 不等高cell搭建(二)
- XMl的解析简单的方法
- VC++ 使用WebBrowser控件中html文件以资源形式加载
- Linux清除磁盘上的RAID信息
- VMware上安装MS-DOS 6.22之一:基本系统的安装
- CSS3 3D的总结(初学者易懂)
- Spring Boot快速入门
- Android特效专辑(二)——ViewPager渲染背景颜色渐变(引导页)
- centos7版本中ssh相关的设置
- adb 安装安卓包
- Python文件读写及网站显示
- node vue 开发环境部署时,外部访问页面出现: Invalid Host header 服务器域名访问出现的问题
- VS2010 重命名文件:源文件名和目标文件名相同 的解决方案