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

前言

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

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

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

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

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

后端 API 返回值规范初稿

规范针对群体

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

规范细节

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

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

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

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

1. resultCode 表示服务端处理结果代码，用 3 位数字表示通用处理结果代码，用 4 位及以上数字表示业务处理结果代码，通用处理结果代码有：
   200 表示处理成功
   400 表示参数错误
   500 表示服务器内部错误
   503 表示当前服务不可用
   504 表示网关超时
2. data 表示返回的数据，如果没有数据时返回 null
3. 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 认证）。