采取 RESTful 风格的 api 是否应该对结果包一层？

[h82258652]

RT，今天公司的新项目开始对接，app 端的一看我这接口就吐槽我。让我改成如下这种： { "code": 200, "message": "", "data": xxx }

但我觉得首先这 code 肯定是多余的，可以直接从 http 状态码里面读取。之前也看过 twitter 的 api，也没有说包一层，200 的话那就直接返回 data 了。 公司项目我就忍忍算了，毕竟人家老员工。但后面有自己项目的话，还是想弄标准一点。不知道一般来说，大家是怎样实现？

[mdluo]

https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#envelope

[chendy]

讲真，这样设计接口的人，大概是不知道有 http 状态码
类似的道理，还有用参数指定返回格式的人，大概是不知道 Accept 头（可能也不知道 Content-Type
但是，如果真的形成了规范，大家都遵守（最好有现成的代码处理这一层），运行也没问题，那就无所谓了，犯不上为了优雅破坏稳定性

[lihongming]

code 一般不是 http 状态，而是自定义的状态。比如 0 表示无错，客户端只有收到 0 才会去处理 data，否则就去看 errorMessage 了。

[unicloud]

根据我自己的使用经验，这里的 code，显然是偏业务的状态码，而不是 http 状态码；毕竟，在一些复杂的场景，现有的 http 状态码不能完全覆盖或很好的描述当前的业务行为。即便 http code 够用，我也不打算完全依赖它，这是设计原则和标准问题。

[wangyzj]

response:{
responseCode:200，
data:{
"code":0,
"data":[],
"success":true,
"msg":"get data success"
}
}

[wpblank]

自己的应用有一套自己自定义的 code 也未尝不可吧

[mdluo]

Make RESTful REST again, 请。
简单化、（尽力）遵循规范 (Convention) 不好吗，为什么非要加一些不直观、不看文档全靠猜的东西？

[good758]

按规范来。对以后好。

[zgqq]

code 可以用来定位哪些业务，更快排查问题

[ke1e]

一般会包装，参考微信公共 api 的返回结构

[xh520630]

公司可以有一套自己的 code。非要说大公司的话，绝大多数的大公司都有一大批错误 code
随便贴一个 https://developers.weixin.qq.com/doc/offiaccount/Getting_Started/Global_Return_Code.html
200 只是人习惯用的没啥不行有的人就喜欢 0 表示 ojbk。

[ericgui]

你的前端没问题

你要学会换位思考

同一个问题，解决思路很多，而且无所谓对错，是“范式”不同

[good758]

code 在匹配时很有用，调用时别人一下就可以快速做判断错误 http 状态最容易欺骗人
数字是最没的多音字不容易出错的的符号
成功还好，失败 应该怎么判断错误原因呢并做操作呢。不是一样又要一个错误规范吗，人来读吗

[airyland]

code 是需要的，尤其是不同错误在前端需要做不同处理时。错误文案可能会变，根据 code 作处理才是正确的。

[hakono]

没什么好吐槽的，真的
楼主觉得靠个 http status 就能解决掉状态码，是没遇到过要返回 N 多不同的错误的情况。当一个 api 或者系统需求复杂起来，区区的 http status 根本不够用。表示错误的状态码就那几个，但你业务的错误逻辑有十几个几十个，这时候你最后就会自然用起 { "code": xxxxx, "message": "" } 了，这时候是不是得感叹下自己活成了最讨厌的样子。。。

RESTful 说到底也不过是个风格，并非限制死的东西，实际业务需求的复杂是根本无法靠一个 RESTful 全部解决的（虽说 RESTful 是适用资源类的 api，但有时候你资源类 api 的业务逻辑也能复杂的一批）

[ochatokori]

赞成需要 code
restful 风格可以参考，完全实施有点不符合实际
不常用的 http 状态码可能会在奇葩浏览器上有奇葩默认行为

[version]

加 code 是没错的，这个是自定义业务的错误码，原则上全部接口都是 200 状态码，而且最好是换个单词，减少其它语言关键字的问题
标准是标准，但也存在弊端，接第三方 api 就明白，大部分国内都是走业务 code 状态码，国外比较多走 restful，不过对于细到具体业务错误来说，捕获 http 全局不太好丢回给子模块，对于接收人来说比较累

[helone]

我个人实践中比较喜欢 restful，2xx 代表成功 常用 200 201 204 4xx 客户端 5xx 服务端，完全够用

自己业务想抛个自己的错误记个日志不行吗？客户端只需要知道错误的 message 就行了

说自己业务复杂 http code 不够用的我是服了的，那你一个页面几百个字段，随便缺一个就留一个 code 这谁顶得住，就不能用 errors 描述下吗？

[vjnjc]

肯定是要的。只是他数值正好是 200 让你很不爽，比如我设计的就简单了，0 访问失败，1 访问成功，2 ～ 99 各不相同。

[nvkou]

跟着行业标准走。自己再搞状态码只会让人不断吐槽。
合着搞半天我还要区分协议状态和业务状态？那后面是不是还要把 encode types, cache control, authorization 这些也再写进业务？好好的工具包不用，非得造轮子

[hoyixi]

又是个没有设计文档的公司

[starerlloll]

code 肯定是要的。。。有的时候业务需求不仅仅是显示 error， 而是根据 code 来显示不同的页面。
你用 error message 来做的话就要疯了。。

[loading]

只要服务器能接到请求我就返回 http 200
业务上的错误我用 code。
例如找不到请求要的东西，我会 http 200 code404

如果用 http 404，不好判断是 url 没写代码处理还是内部逻辑错误了。

[loading]

同时我还带 msg，这是给人看的，一般通用于弹提示框“找不到 xx”

[ericgui]

@loading +1

[eason1874]

借用知乎的名言：先问是不是，再问为什么。

楼主和楼上其中几位别胡扯了，90% 以上正经产品接口都有自己的一套 Error Codes，包括楼主说的 Twitter 在内，不信自己看（ https://developer.twitter.com/en/docs/basics/response-codes ）。

HTTP Status Code 根本不够用，我举个例子，用户登录可能出现的错误包括但不限于账户不存在、账户名或密码错误、验证码错误、账户登录受限（包括各种原因），在程序层面只有 403 Forbidden 那你就只知道登录不了，不知道登录不了的原因，不能根据不同的情况去引导用户进行下一步操作。

[mamahaha]

有规范听规范的，没规范听官大的。

[infra]

楼上说的很对。
包装一层未必就不合适了

[fanyingmao]

@vjnjc 0 一般都是表示成功的，现在接的项目也是 0 失败，1 成功，这种非主流好烦。

[Salvation]

看了楼上一些言论，简直笑了。

首先很多人没有遇到过这种场景，所以有点想当然地表示，http 状态码就够用了。如果在某些场景下，100%够用，并且不用考虑未来的扩展性，那全部人都按照完全 restful 的方式来，也是一种办法。

但是很明显，这种可能性很低。举个最简单例子，一个请求失败了，但是产品上做了优化，针对不同的失败原因，进行不同的展示，请问这个怎么实现，用 http 的状态码一个一个套？很明显这里就需要某些 code 是红色的警告，某些是黄色的警告，某些是个弹窗通知。

归根到底，还是场面见得不够多，并且没有深入思考一些已有方案的内在合理性的结果。

[kanezeng]

我之所以都单独加一层 code，更灵活的表达其实是其次，主要是不想把系统状态和业务状态混在一起

[dotw2x]

用作表示业务状态，没毛病。

[Nasei]

@eason1874 自定义错误码是需要的，但 Twitter 的接口，那些错误码是在 40x 或者 50x 返回的，而且那些码避开了常用 http 状态码的值，但国内很多都是 200 的状态码然后内容里还有一个 200 的 code…甚至所有接口返回 200 只用里面的 code

[h82258652]

@eason1874 我的意思跟楼上 Nasei 的意思一样。在错误情况下，有多种错误而且客户端需求根据错误进行不同操作，那 code 肯定是必要的。但是我主楼的意思是在 200 的情况下，还包一层是真的多余。例如 GET /person/1，有就 200 返回个对象 json，没有就扔个 404 就是了。

[h82258652]

@mdluo 谢谢，收藏了

[justfindu]

我给前端是 200 直接返回 data 数据, 其他错误 返回 message 和 code 格式, 定位错误.

[eason1874]

@Nasei #33 几年前还没普及 HTTPS 的时候，HTTP 接口大多是 200 状态，因为 404 之类的状态会被一些地方运营商和路由器劫持。这种东西只要有个统一规范就行了，既然 HTTP 状态码满足不了需求，统一用数据的状态码无伤大雅。

[xaplux]

肯定要啊，很多情况需要有一套自己的 error code 的，表示一些更细力度的问题，比如下单，下单的时候价格变动，会导致下单失败的，优惠券过期也会导致下单失败，不能都用 400 表示的，那怎么区分是因为价格变动还是优惠券过期导致的下单失败

[ampedee]

@eason1874 你发的链接没看出来和楼主说的有什么冲突。
第一段就写了:
The standard Twitter API returns HTTP status codes in addition to JSON-based error codes and messages.

The Twitter API attempts to return appropriate HTTP status codes for every request.

返回正确的状态码是大前提，只有 error response 才用 code 对具体的错误进行标识，方便客户端查找文档和解决方案。这个 code 换成字符串或者 url 都是可以的，关于 error response 具体可以看看 RFC7808

[yamedie]

{ "code": 7001, "message": "短信验证码已失效", "data": null }
{ "code": 7002, "message": "短信验证码错误", "data": null }
{ "code": 7003, "message": "尚未发送短信验证码", "data": null }
{ "code": 7010, "message": "当前手机号已领取过会员权益，请勿重复领取", "data": null }
{ "code": 9001, "message": "登录已失效，请重新登录", "data": null }
以上报文是我瞎编的，单就一个短信验证码提交接口就有 n 种错误的可能，当（业务上的）错误发生时，data 已经不重要，重要的是 code 和 message，前端依据 code 进行相应的交互，后端也能根据 code 排查异常，message 足够友好的话甚至可以直接吐司给用户，多优雅的设计

[IvanLi127]

总感觉在非 200 的情况下包一层自定义信息似乎蛮折中的

[Varobjs]

封装一层还得有必要的，
业务错误不能全部靠 http status 来处理，比如当前来不及处理，请重试，调用方如何判断这种情况，然后重试，只能通过 code 啊。

[Ianchen]

把 Http 状态码再自己包装一层, 我个人觉得是没意义的事. 但是自定义 code 我是一直在用的, 并且就楼里所说, 我觉得什么情况下错误码够用? 你要自己去思考. 我在给公司设计错误代码规范的时候是规定, 如果前端需要服务端返回特定的 code 码来处理一些后续逻辑, 则给固定一个唯一的, 如果不需要, 仅仅是错误提示, 只要统一的错误码即可. 错误码在大部分情况下对前端及用户来说是无任何意义的(除非你想跟踪问题, 但是跟踪问题, 日志就可以了). 当然这种情况在写开放 api 接口的时候会参考 A,T 的错误码

[tt67wq]

@chendy 可是蚂蚁金服和微信平台的 API 接口都是有业务错误码的

[zsdroid]

@h82258652 #32 你这样做，数据结构不统一啊

[vbonluk]

建议楼主可以看看微信微博等等 sdk 的接口，一般会包一层，用于自定义状态码。前端根据不同状态码不同处理。

[eason1874]

@h82258652 #34
@ampedee #39

那是我理解错了。我看楼主帖子只说了可以从 HTTP 状态码读，没说仅限 200 状态，我以为楼主跟评论区说 HTTP 状态码够用的一样。

[Orenoid]

我都不知道是第几次在 v 站看到这个问题了

[Narcissu5]

@yamedie

{ "code": 7001, "message": "短信验证码已失效", "data": null }
{ "code": 7002, "message": "短信验证码错误", "data": null }
{ "code": 7003, "message": "尚未发送短信验证码", "data": null }
{ "code": 7010, "message": "当前手机号已领取过会员权益，请勿重复领取", "data": null }
{ "code": 9001, "message": "登录已失效，请重新登录", "data": null }

毫无意义，99%的情况下前端根本不会在意为什么出错了，前端只需要知道请求成功或者失败了，失败了把错误消息弹出来就完了，http 200 足已

最重要的是

封装之后无法做监控
封装之后无法做监控
封装之后无法做监控

重要的事情说三遍

[harde]

http 代码用来表示通讯层状态。
code 用来表示业务代码，没毛病。

[xuanbg]

错误通过 HTTP 状态码识别的怕是没真实实践过吧？就说 404 好了，到底是服务不存在呢？还是接口不存在呢？还是资源不存在呢？懵逼了吧。

如果是封装的，那前端判断问题就简单多了。http404，那就是服务没起或者接口没写好。code404，那就是服务一切正常，而是真的没这个资源。

[baiyi]

200 直接返回数据，非 200 再返回业务码，也不要带上 {"data":null} 这样的字段，太蠢了

唯一要考虑的是 ios，根据他使用的框架和语言，要考虑将 [] 封装为 {}

[binux]

成功的时候直接返回对象就行了，错误有错误的 object 定义，里面再用 code。

[yuan7712]

@Narcissu5 前端很多场景并不是只关心成功失败，其次封装之后也是可以监控额

[Ianchen]

@yamedie 我觉得短信 70xx 的代码无任何存在的意义, 用户不关心错误代码是什么, 前端拿到错误代码也不做任务处理, 何必花时间与精力去维护越来越多的错误代码呢? 服务端写返回的时候还要去查代码是不是已经存在了. 这种错误包括但不限于: xx 输入不合法, xx 未填写, 校验不通过, 提交失败等 统一一个非 0 的 code 即可如 code: -1, 可适用于绝大部分的逻辑中断返回

[caryqy]

HTTP 的那几个码不够用

[fiypig]

难道你们都没 code 的吗 , 我蒙蔽

[Narcissu5]

@eason1874 实际上登录这种错误就只能返回统一的 forbidden，过于详细的信息是漏洞。我们刚刚被审计逼着改掉

[yc8332]

明显那个不是你说的 http 状态码，而是业务里面的错误代码。。

[h82258652]

@vbonluk 微信我没弄过，但是微博我之前开发 app 集成过。但实际上微博的 error code 我也只用了 access token 过期这个，其它直接显示个 message 就是了。另外吐槽一句，微博扔回来的 error code，有些压根文档里找不到的……

[petelin]

这是一道好的面试题
嘻嘻😁

[Narcissu5]

@yuan7712 不可能，不会有哪家监控把 body 拆开了看，何况监控看的是统计数据，每个接口的 businesscode 都不一样没办法汇总。

再者，非 200 返回的时候也是可以带 code 的，那走的就是异常流程了

[h82258652]

@yc8332 不，楼主我说的就是正常 200 的情况，例如 GET /person/1，我前端的意思是这样也要包一层。

[ryougifujino]

感觉还是 twitter 那样好，成功的时候直接返回不包一层，失败且有必要的时候再提供 code 进行进一步判断

[Ixizi]

包不包都无所谓 能用就行

[sm0king]

打一架，谁赢了听谁的。

[Leigg]

我想问楼主工作几年？

[WeKeey]

之前公司的原则是只用 errorCode，httpCode 一律 200

我自己的项目是正常 httpCode 200，直接返回内容，异常 httpCode 400，500 等，返回 code 和 message

自己的接口： https://xapi.vip/

参考： https://github.com/cryptlex/rest-api-response-format

[OSF2E]

那么问题来了，是给不了，还是不想给，或者他是不是故意为难你。

放下对人心的揣测，真的很难。

[eason1874]

@Narcissu5 #58 登录错误提示能有什么漏洞，最大的可能也就是穷举，做好访问限制什么都不用怕，单 IP 三次错误以上放验证码，全网十分钟内错误超过日常平均值*3 全网放验证码。

[Vegetable]

你用 http 状态码表示一下用户 token 即将过期，请主动刷新这个状态

[cmobiooo]

如果内部错误，http code 返回 200 然后 json 里的 code 为自定义错误码还能理解

不能理解的是：
HTTP CODE：200
{
"code": 404,
"msg": "page not found"
}

[dog82]

业务向的 code 是必须的，http 那几个状态码很难表达更多意思，但是我反对用数字的 code，用字符串更合理

[jorneyr]

对你的要求没有问题。

参考各大厂的 API，这个 code 是有必要的，请求会根据传的参数给你提示有什么错误，例如提示你缺少某个参数，这种业务逻辑的错误不是 HTTP code 能做到的，因为错误千奇百怪，根据 code 可以查询参考文档知道是什么错误，code 不变，参考文档可以写多种语言版本。

[unco020511]

我认为是有必要的,有时候业务逻辑有多种错误状态,需要一个 errorCode 来区分

[geying]

@helone 请教一下假设 楼上讲的登录失败，如何从日志快速定位问题，感觉设置错误码会不会更容易定位直接在错误位置开始调试。目前的系统日志量挺大的如果要找边缘业务报错感觉很麻烦

[blackboom]

200 包一层太蠢了，不要谈什么阿里腾讯。

[rykka]

当然要包。这才多大的数据量。但是用起来省事多了

[Airon]

我司定义的是，成功直接返回 data 错误返回各种 error code 和 error massage，我感觉还挺好的，http code 很难表现复杂逻辑的多种错误。公共错误通过 http code 体现 比如用户验证 啥的

[dcsite]

看了上面很多人的回复：自定义 code 无意义。我怀疑这些人是不是只写过留言板之类的应用？开发的 API 接口，不需要对公司其它部门提供服务，也不会接入其它平台。更不需要对外提供服务。

[zhuangzhuang1988]

能用就行, 统一就好

[nisnaker]

@Ianchen #55
我觉得短信 70xx 的代码无任何存在的意义, 用户不关心错误代码是什么, 前端拿到错误代码也不做任务处理
---------------
我觉得所有错误代码无任何存在的意义, 用户不关心错误代码是什么，然后你们前端真牛 x，返回错误啥也不干

[yamedie]

@Ianchen 当然有交互, 比如验证码已失效请重新获取, 吐司的同时自动清空验证码输入框 / 登录已超时请重新登录, 吐司后 3 秒钟自动跳到登录页面就是最常见的交互. 产品经理想给你定义的交互比这些多着呢.

"前端拿到错误代码也不做任务处理, 何必花时间与精力去维护越来越多的错误代码呢?" 凭这句话我能判断你不是一个前端吗?

[yamedie]

@Narcissu5 同 83 楼

[jackchao7432]

@mdluo 那业务场景很复杂,http code 不能较好地描述错误,你怎么办?

[jackchao7432]

@dcsite 这还真不好说,外包从业人员、小公司、学生、zf 部门....估计是这样一个群体

[icris]

@cmobiooo #72
http 404 浏览器会有友好提示页面，不在 code 里写 404 我记得是挺通用的做法

[g1475117007]

我觉得需要，我拿到 code 才能根据 code 内容去做提示或者跳转这类的东西。

[pkoukk]

@Narcissu5 不是很赞成，例如登录失效这种，前端就可以直接处理成自动跳转到登陆页面。而账号 /密码错误就纯吐司提示即可。业务上很多时候不能告诉用户：“你错了”，而是友善的提示用户你该怎么做。这个时候 code 就很重要了

[aa81425600]

笑死我了，你要用不同状态反馈用户不同信息不用 code 字段拿头判断吗？
比如说支付失败，究竟是余额不足还是密码错误，你让前端解析你反馈的 message 然后返回不同的效果吗

[chenxiaohong]

Code 有它实际的业务需求。客户端查询一个资源，HTTP 状态返回 404，这是我 URL 写错了，还是我查询的关键字没有匹配的值？

[passerbytiny]

@h82258652 RESTful 风格要求的是“使用 HTTP 状态码指示接口的执行结果”，并不是“只使用 HTTP 状态码指示结果”，它并不反对你同时使用 HTTP 状态码和数据中的“code”。结果包一层并不违反 RESTful 风格。当然，恒定 HTTP 200，仅使用数据中的“code”表示错误码，这是违反风格的。

一个优良的服务或接口应该在尽量简单的情况下兼容不同的前端，有些前端——比如临时测试并且操作人还懒得打开 F12 的浏览器——可能没有接受 HTTP 状态码的能力，这时候他就需要从返回的 JSON 数据中去获取 HTTP 状态码。一个优良的接口，首先肯定要根据实际情况返回 HTTP 状态码，其次返回内容应该是这样的：
HTTP CODE：NNN
{
"http_code": NNN,
"message": "bula bula",
"main_data":{...}
}
或者是这样的：
HTTP CODE：NNN
{
"http_code": NNN,
"businesslogic_code": NNNNNNN,
"message": "bula bula",
"main_data":{...}
}
第二种情况，如果没有提供 businesslogic_code 的翻译器，businesslogic_code 不管是对前端程序还是对前端的用户来说，都是神秘代码，屁用没有（这个代码，windows 生态中的 800nnnnnxxx 错误代码，是个典型的代表）。在错误反馈中，字符串类型的 message 才是必要的，数字 code 只是可选的。

[broadliyn]

v2 一堆把 restful 奉为圭臬的都是没毕业的学生？？

[Amayadream]

@Narcissu5 #49
1.前端需要关心接口细分的错误类型，从而做配套展示和处理，说不关心可以理解你不是前端也不懂前端。
2.恰恰相反，做业务 code 码封装之后反而更好做监控，监控粒度更细，更容易发现问题。

[newtype0092]

这个问题真好，一下就能分辨出那些人是真的有工作经验的，哪些人是只做过作业、毕设或者个人小玩具的。。。

[HangoX]

http 状态码用来做业务是够用的，410 到 500 之间有 90 的数字，一个接口的状态足够表示了。问题在于中国的网络环境，有些网关，运营商会对非 20x 的返回进行拦截,然后返回自己的数据，这个时候你的接口就得不到正确的信息了。之前有个开发者是分享过这个事情的，被运营商坑成狗。所以我还是建议自己做 code

[passerbytiny]

@icris #79 http 404 的友好返回是：HTTP CODE 404，并且 body 做一个像那么回事的界面。见 https://github.com/bbbbbb/bbbbb，你需要开发者工具才能看到返回的 HTTP 状态码。HTTP 404 只是个状态码，并不表示浏览器遇到 404 就不会继续显示页面；而 HTTP 200 + 404 界面，对浏览器之外的其他前端——比如搜索引擎——可能产生干扰。

[newtype0092]

@mdluo 感谢分享
之前看很多 RESTful 的文章感觉太简单了，只能用在一些“无欲无求”的项目。。。这篇文章里的东西实用多了，不愧 Best Practices

[leopardwei]

定制 600 以上的 code，如果需要的话。包一层的话，好处是觉着清晰了些。弊端是错误码将分 http、业务两种，有些繁琐了，如果对带宽有要求（业务繁忙）也会加大数据量传输。

[so1n]

code 很有用，只是 200 会让你以为是 http code 而已