[规范制定征求] 后端 API 接口返回值

前言

我们公司正在快速发展状态，是时候开始制定各项技术标准规范（各种技术栈的语言规范）和工作流程从开发、测试到上线等）了，否则后期越来越玩不转。

前期虽然有引进各种规范，但总是支离破碎，而且有很多地方也不太符合我们公司工程师口味，所以也没有继续执行下去。

最近我们在开始整理各种技术规范和流程，会经历以下流程：

内部主要人员（主要是是几个 TL ）进行初稿审定，提出问题、分析问题、指定初稿。
形成初稿后不仅在公司内部公示，不涉密部分还要在网上公示（重点）
接收大家的意见和建议，综合各方意见并权衡利弊，确定一种方案开始在各团队中试行。
后续再开发中遇到问题后，再升级规范。

今天我们公示一下我们公司的初稿，并解释其中的原因，也广泛征求大家的意见和建议，大家的每一条建议我们都会深入思考和论证的。后续我们还会有很多类似的规范拿出来和大家一起交流，不吝赐教。

后端 API 返回值规范初稿

规范针对群体

服务端、服务端对接端（网页端、APP 端、小程序端）

规范细节

正常的后端接口响应，HTTP Status Code 默认返回 200，只有在下列情况时接口才会出现非 200 的情况：

当服务端鉴权失败时返回 HTTP Status Code 401
中间环节三方软件返回的标准错误码，例如 Nginx 返回的 5** 错误码

当接口 HTTP Status Code 为 200 时，返回的结构如下：

{
  "resultCode": 200,
  "data": null,
  "errorMsg": ""
}

resultCode 表示服务端处理结果代码，用 3 位数字表示通用处理结果代码，用 4 位及以上数字表示业务处理结果代码，通用处理结果代码有：
200 表示处理成功
400 表示参数错误
500 表示服务器内部错误
503 表示当前服务不可用
504 表示网关超时
data 表示返回的数据，如果没有数据时返回 null
errorMsg 表示错误时的返回信息，如果没有错误时返回空字符串，始终不能为 null

当接口 HTTP Status Code 非 200 时，返回的结构如下：

{
  "resultCode": {通用处理结果代码},
  "data": null,
  "errorMsg": "对应的错误消息"
}

三方软件 HTTP Status Code 非 200 时，我们对内容不可控，对接端要做好拿不到返回 body 的准备

针对初稿里面的若干问题思考，也希望大家多提意见和建议

为什么我们的返回都尽量采用 HTTP Status Code 为 200 ？
答：经过公司内部对接端同事们的意见，如果返回的是非 200 状态码，目前很多框架会在框架层直接拦截，不会进一步解析消息体，不方便拿到服务端返回的错误消息。
[重点讨论] 那为什么鉴权失败时要返回 HTTP Status Code 401 呢？
答：目前我们的 APP 中有通过 WebView 嵌套网页，网页里面又有 Ajax 的调用。

之前我们的流程是，APP 内如果需要打开网页，则需要通过一个固定的链接进行转换，例如本身要访问 a 链接，则务必访问跳转链接并添加参数 b?targetUrl=a，同时携带 APP 的鉴权参数（ APP 我们是把鉴权参数放到 header 里面的），服务端拿到 APP 的鉴权信息后会回写 cookie 到网页中，同时引导跳转到真正的目标地址。

上述流程里面就会出现一个问题，当 APP 里面的鉴权信息（ Token ）没有过期，但网页中的鉴权信息过期了（例如一些不可抗拒因素导致某台服务器丢失了网页端的 session ），用户再点击网页里面的内容，则始终会报告失败，给用户一种很不好的体验。

之前我们是通过 bridge 的形式由网页端通知 APP 端发起重新跳转，如果本次跳转 APP 鉴权信息依然有效则按照前述流程正常打开网页，如果本次跳转发现 APP 的鉴权信息也失效了，则引导用户在 APP 中重新登录。根据我们的经验，bridge 这种方式很容易出现兼容性问题，在某些机型上无法通知 APP，导致用户始终卡在网页上（用户并不知道要重启 APP，只知道找客服）

为了让用户得到更好的体验，我们打算在 APP 层面捕捉 webview 的所有请求，一旦发现 HTTP Status Code 为 401 的情况，就引导 APP 重新登录，简单粗暴，不过会忽略 APP Token 有效，网页 Token 无效这种情况。

如果把 401 放到返回 body 里面，不方便 APP 统一捕捉返回信息。

针对 APP 打开网页，网页里面有网页跳转或者接口请求这种情况，大家还有更好的方案吗？
答：我们的目的是能够更好地处理错误流程。也希望大家多多指导，不胜感激。

如果按照上述我们的方案，我们的接口需要接收 cookie 这种鉴权方式（ APP 内打开的网页通过 ajax 调用），也需要接收 header 这种鉴权方式（ APP 直接请求）；我们的网页需要接收 header 这种鉴权方式（ APP 通过跳转链接打开目的网页时），也需要接收 cookie 这种鉴权方式（正常情况下都通过 cookie 认证）。