内容简介: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,不管它从属于谁。
以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持 码农网
猜你喜欢:- 架构设计(7)——如何设计一个架构
- 架构设计(8)—高可用架构设计
- 如何设计实时数据平台(设计篇)
- Token经济设计专家叶开:Token设计画布与10大设计模式
- 数据可视化设计(1)情感化设计指导可视化设计理念
- 架构设计笔记(八):详细方案设计
本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们。
Google 广告高阶优化(第3版)
【美】Brad Geddes(布兰德.盖兹) / 宫鑫、康宁、王娜 / 电子工业出版社 / 2015-9 / 99.00元
《Google 广告高阶优化(第3版)》可以说是Google AdWords的终极指南,内容非常丰富,第三版在内容上进行了全面更新。介绍了AdWords的最新最完整的功能,阐释其工作原理,也提供了相应的优化方法、策略和实践教程,读者可以随时在自己的PPC广告系列中进行实践。第三版增添了50多页新内容,涵盖Google系统最近的所有变动,包括广告系列结构的变化、出价调整器、重定向、视频广告功能、全新......一起来看看 《Google 广告高阶优化(第3版)》 这本书的介绍吧!