Web 技术研究所

我一直坚信着,Web 将会成为未来应用程序的主流

REST API 设计之 —— 错误格式

  当一个请求失败时总是伴随着一串数据,后端要告诉前端到底为什么出错,甚至可以把可能的解决方案都带上,这样可以有效地提升 Debug 效率。当然也有很多时候后端会觉得细化错误信息是一件无聊的工作,所以很不负责任的抛出一个「未知错误」,于是就各种呵呵了。

细化错误

  我觉得错误就是要细化到点上,甚至还要提供排错方案。在错误描述中说出自己无法处理请求的原因,告诉前端缺少什么参数或什么参数的取值不正确。这样前端甚至不用去翻阅文档就可以根据错误提示来解决遇到的问题。
  其实细化错误不仅是后端要做的,前端在给用户提示信息时要是能够细化错误也可以有效地提高体验。比如验证手机号,如果出现非法字符就提示用户里面有非法字符。这时用户可能会立刻去检查是否有非数字存在。甚至更高端点的情况可以检查全角数字,当用户不小心输入全角数字时给予正确的引导。还有位数等一系列细化的判断,这里就逐不一说明了。其实扯到这里已经有点离题了,总之在 API 的错误设计中细化错误是很重要的。

状态码

  虽然 4xx 和 5xx 两种状态码对于前端的 XHR 对象而言并没什么不同,都只是进入错误处理而已。但是各种状态码的语义如果正确的话有时候甚至只要在控制台的网络面板就能知道到底发生了什么,省得去翻阅错误信息。但是使用各种错误状态码也有个坑,REST API 的控制台和网络面板像是来了大姨妈似得一片红。简直难看到爆!浏览器也没有提供相应的接口来让一些预料之内的 HTTP 状态码不泛红。总之就是个坑!

使用字符串错误名

  曾经,大量的 API 在错误时都会给一个数值的错误码(貌似是被 Windows 带坏的)。错误码当然很重要,但数值型的实在不怎么样。看到一串数值错误码就必须去查文档才能知道这个错误的含义。如果将「错误码」以字符串常量的形式描述为「错误名」,那么只要读到这些字符串就可以大致地看出是什么错误,这才是最体贴的方案。

错误对象的设计

  每个错误都是一个错误对象,因为它们有「错误名」及其它错误信息。比如「错误描述」、「错误堆栈」等。以一种什么样的结构来收纳它们是个问题。在很早以前我曾以 {"msg":"错误描述","err":错误码} 的形式去描述错误,后来发现这些缩写的通用性太低了,在翻阅过一大堆标准的错误格式后,最终我还是看上了 JS 原生的 Error 对象结构:{"name":"错误名","message":"错误描述"}。使用这个结构的话,即使是 Promise 产生的其他 JS 错误也可以正常处理了。

  其实比起其他方面的设计,错误对象的坑并不多。而且有一个 JS 原生 Error 对象这个轮子可以参考,所以错误对象设计其实算是最简单的部分了。我们的设计理念是标准化。使用标准化的东西,即使别人不翻文档也可以猜到用法,这才是最好的设计。

网名:
34.203.245.*
电子邮箱:
仅用于接收通知
提交 悄悄的告诉你,Ctrl+Enter 可以提交哦
神奇海螺
[查看全部主题]
各类Web技术问题讨论区
发起新主题
本模块采用即时聊天邮件通知的模式
让钛合金F5成为历史吧!
次碳酸钴的技术博客,文章原创,转载请保留原文链接 ^_^