Restful API 设计(二)

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

内容简介:2015年冬天,我写下第一篇也是目前唯一一篇关于 Restful API 设计的文章。时间过的飞快,转眼三年前过去了。这三年间经历过的项目中,后台逐渐微服务化,restful 也成为大家耳熟能详的设计方案。这里记下些自己的经验和教训,以供对照。基本的 code 原则很简单,2xx 表示成功,4xx 表示客户端错误,5xx 表示服务端错误。那如何分辨是客户端还是服务端错误呢?我总结了以下几种常见的客户端错误,以及对应的错误码。

2015年冬天,我写下第一篇也是目前唯一一篇关于 Restful API 设计的文章。时间过的飞快,转眼三年前过去了。这三年间经历过的项目中,后台逐渐微服务化,restful 也成为大家耳熟能详的设计方案。这里记下些自己的经验和教训,以供对照。

Status code

基本的 code 原则很简单,2xx 表示成功,4xx 表示客户端错误,5xx 表示服务端错误。

那如何分辨是客户端还是服务端错误呢?我总结了以下几种常见的客户端错误,以及对应的错误码。

  • 401 - 未授权的访问比如访问资源需要 token 鉴权,如果不携带 token 或者 token 已过期,则返回 401.
  • 403 - forbidden,禁止访问。比如某些资源只允许管理员访问,非管理员则返回 403。
  • 404 - not found,不存在。

总之,凡是客户的锅,都返回 4xx 。如果恰好不在上面所列的三种情况中,则用 400 代替。

服务端自身错误则包含两类情况:

  • io 错误,比如读写文件,访问数据库
  • 自身逻辑错误,比如内存泄漏。

第一种错误是不可避免的,属于不可控的外部环境问题。第二种错误虽然可以通过 review 代码加上各种测试来预防,但 最好 有个兜底的错误处理以免程序挂掉。

我司对于服务端错误统一返回 500(internal server error),因为考虑到服务端错误对于客户来讲毫无建设意义,毕竟客户绝对没有办法帮助我们解决错误。即使对于工程师来说,日志也比 code 更有表现力。相对而言,客户端错误则尽量设计的详细因为大部分情况下客户端要据此来引导用户回到正常的业务中来。比如,如果返回 401,则引导用户登陆或者注册。如果业务比较复杂,还要考虑扩展 reponse 来指明更加具体的错误。如:

400 bad request
{
  "code": 123,
  "message": "Name is required"
}

List API

GET /orders

200 OK
{
 "offset": 0,
 "limit": 20,
 "count": 100,
 "elements": [...]
}

对于这个 List API,如果资源不存在,返回应该是什么。受 404 概念的普及影响,很多人会选择返回

404 NotFound

难道说,如果不存在 orders(订单) 就是错误吗?比如我从来没有在淘宝下过单,那订单列表也就应该显示客户端错误吗?这显然是不对的。实际上,404 是指所请求的资源不存在。而对于 orders 来说,它是一个集合概念。不管下没下过单,这个集合总归是存在的。按照这个理论,正确的返回应该是:

200 OK
{
 "offset": 0,
 "limit": 20,
 "count": 100,
 "elements": [] // 空数组
}

所以对于 List API 来说,没有 404。

Parent resource

restful API 的路径可以表现资源的从属关系。比如,用户可以有多个地址。

/users/{user_id}/addresses/

那么,对于一个并不存在的用户而言,访问上述 API,应该返回什么?

用户不存在,他的地址也必然不存在,那似乎是个简单的客户端错误。但我们确实有必要参考 Parent resource 的状态吗?这从理论上讲似乎毫无破绽,但实际操作及其困难。假如 Parent resource 的状态为 s1, Child resource 的状态为 s2,如果必须参考 s1 才能定义 s2,则 Child resource 的状态为 s1 s2。这还是简单的层次,如果 Parent 之上还有 Parent,则最终 Child 的状态会变成 s0 s1 * s2。如果随着业务的升级,每个节点的状态推算都要这样越来越复杂,那结果必然是整个系统的崩塌。

所以,目前比较推崇的做法是,仅仅考虑目标资源或者资源集合的状态。即,addresses,不管它从属于谁。


以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持 码农网

查看所有标签

猜你喜欢:

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

Vue.js前端开发

Vue.js前端开发

陈陆扬 / 人民邮电出版社 / 2017-2-1 / CNY 45.00

本书分为10章,包括简介、基础特性、指令、过滤器、过渡、组件、状态管理、常用插件、工程实例和Weex打包。本书从简单的单个实例和基础语法,到工程实例,将系统地讲述Vue.js在项目中的适用场景和具体操作。本书的特点在于案例详实,使读者体会到框架的优点和便捷之处,提升开发效率,最后能将Vue.js运用到实际项目中,避免纸上谈兵的尴尬。一起来看看 《Vue.js前端开发》 这本书的介绍吧!

SHA 加密
SHA 加密

SHA 加密工具

RGB HSV 转换
RGB HSV 转换

RGB HSV 互转工具

HEX HSV 转换工具
HEX HSV 转换工具

HEX HSV 互换工具