RESTful API 中的 Status code 是否要遵守规范

栏目: 后端 · 前端 · 发布时间: 5年前

内容简介:事情是这样的,我在知乎受到邀请回答一般那种说特殊情况特殊处理,不要拘泥于规范的人,大多都是自己没搞清楚某些知识,拿这句话当作偷懒的借口。其实一般做项目没那么多特殊情况。大部分完善的 HTTP 请求库,都会依照 RFC 的规范去设计错误处理的流程,虽然处理方式各有不同,但一定会在文档说明错误处理的部分的。使用 RFC 标准能最大限度的兼容各种 HTTP 客户端。你说现在你用的HTTP客户端不处理 Status Code,但是你没法保证将来不重构,重构的时候还是不处理。

缘起

事情是这样的,我在知乎受到邀请回答 一个问题 ,主要是问 ID 找不到到底要不要用 Status 404 。我回答的还是比较早的,那时候只有一两个回答。我本来以为这是没啥争议的,在一个学术的地方讨论学术问题,当然是要遵守规范了,结果过了几个小时大跌眼镜。自造 code 党竟然支持率第一,还好平时见的也很多的全 200 党没有受到支持,不然真的吐血了。

为什么要遵守规范

一般那种说特殊情况特殊处理,不要拘泥于规范的人,大多都是自己没搞清楚某些知识,拿这句话当作偷懒的借口。其实一般做项目没那么多特殊情况。

为了更好的适应各种库

大部分完善的 HTTP 请求库,都会依照 RFC 的规范去设计错误处理的流程,虽然处理方式各有不同,但一定会在文档说明错误处理的部分的。使用 RFC 标准能最大限度的兼容各种 HTTP 客户端。你说现在你用的HTTP客户端不处理 Status Code,但是你没法保证将来不重构,重构的时候还是不处理。

一般调用 api 使用 js 或者 python 的概率比较大,我们看看知名的库。在 js 里,最近比较流行的 axios 默认会把 200 系列外的 code 归到异常里。在 python 里,最流行的 http client 是 requests ,它更为详尽的预处理了 status code 。

为了开发者更好上手

另外在管理团队的方面,我们的原则是尽量的减少一个项目的“规范”,这样才能更容易去遵守。能用标准的地方,一定不要自己定一个更复杂的规则。无论是服务端的维护者还是 API 的消费者是会换人流动的,每个进入项目的人熟悉一大堆无谓的自定义项目规范都要成本。

更简单的办法是参考大厂

其实给项目定规范,最不靠谱的是自己拍脑袋,稍好一点的是去知乎或论坛问,更好一点的是去 google 搜,最简单的是直接去看大厂的产品或者规范啊。 API 本来就是个公开暴露的东西,还有比这更好找参考的吗?我们来看看:

  • Google 遵守规范
  • Github 遵守规范
  • Microsoft 遵守规范 顺便说一句,微软的 API 规范真的很具有指导意义。
  • Twitter 遵守规范
  • 阿里云 遵守规范
  • 腾讯云 不遵守规范 全部 200 事实上腾讯的技术比较混乱,每个项目都不一样。但最新要执行的统一规范是全部 返回 200 用返回值中的错误码表明错误。
  • 百度云 遵守规范

我的建议

很多人也许用着很简陋的 Web 框架,导致误以为返回了错误码,就不能返回 Response Body 了。其实你返回 204 外的任何 Status Code,最好都伴随着返回 Body 。

在项目规范里,可以规定 Status Code 遵照 RFC 标准,或者选定一个集合出来,把一些不常用的去掉。然后如果不是200系列的代码,必须伴随着这样的一个错误结构:

{
    "error": "UserNotFound",
    "message": "该用户没有找到"
 }

这样错误分为了三层结构,第一层是 Status Code,使用者能大概知道是什么问题。第二层Error 是一个 Key 使用约定好的无空格的英文,给使用者做判断用,使用者可以根据 Key 自定义接下来的操作。第三层是 message ,有些 Key 使用者可以决定直接把 Message 显示个终端客户。

如果是微服务项目,需要要求每个服务不管用什么语言,都要把错误统一成这个样子。如果开发者告诉你框架不支持,那这一定不是个好框架,改重构了。好的框架不仅能让你自定义错误内容,还能做到所谓的“框架自己出错的返回”也由你自定义。比如路由没有找到之类的。

最后

我实在不明白为什么一个最扯淡的答案,要自造一个 600 的 status code ,可以得票第一。知乎用户到底有没有一点独立的判断精神啊,只要装的一本正经,再摆出来一点资历,哪怕是胡说八道,大家也纷纷点赞。也许真的不适合在知乎去回答技术问题了。


以上所述就是小编给大家介绍的《RESTful API 中的 Status code 是否要遵守规范》,希望对大家有所帮助,如果大家有任何疑问请给我留言,小编会及时回复大家的。在此也非常感谢大家对 码农网 的支持!

查看所有标签

猜你喜欢:

本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们

降维攻击

降维攻击

高德 / 世界图书出版公司 / 2016-3-31 / 39.80元

本书优势: 第一,降维攻击是一个刚开始流行的商业概念,未来随着电影《三体》的上映,这个概念会更加流行,会成为一个全社会的讨论热点。推出这本书,正好借势营销,是一个热点窗口,同时这个概念的商业价值,又符合了时下市场的需求。 第二,这本书的案例和分析,立足于本土,因为降维攻击的思维,很好地表现了国内许多互联网企业崛起的过程,百度,阿里、腾讯、京东等电商的崛起历程都充满了降维的智慧,对于目前......一起来看看 《降维攻击》 这本书的介绍吧!

HTML 压缩/解压工具
HTML 压缩/解压工具

在线压缩/解压 HTML 代码

HTML 编码/解码
HTML 编码/解码

HTML 编码/解码

SHA 加密
SHA 加密

SHA 加密工具