restful API 的 code 码定义

前言

随着网络应用的不断发展，衍生出了「前后端分离」的基本架构。前后端分离的优势这里不作深入讨论。

前后端完全分离后，多端（浏览器、APP等）和服务端的交互可以通过 API 请求的方式进行，本文主要讨论
restful api 实践中的一环：数据返回格式的定义。

关于 rest 的一些设计原则，可以参考阮一峰总结的两篇文章：

• 《RESTful API 设计指南》
• RESTful API 最佳实践

数据返回格式

数据返回主要要包含以下信息：

1. 服务器的响应状态，起码要知道是成功还是失败是吧
2. 请求的数据内容，比如我获取了产品列表，你要告诉我有哪些产品是吧
3. 请求的更多说明，就是对1的说明，比如失败了，你要告诉我什么原因是吧

总结下来，基本结构为

{
  code: 200,
  data: [
     { name: "xiao mi"},
     { name: "apple"}
  ],
  msg: "success"
}

其中

• code 为接口返回的状态码（和 http 码不太一样，完全可以自己定义）
• data 为返回的数据，为 json 格式，可以是数组，也可以是单条数据
• msg 为 code 的说明，尤其在请求错误时，进行相关描述

需要注意的是，推荐 data 字段采取标准json进行传输，即使是再简单的数据，不要进行自定义格式。这样方便前后端编码

code 的定义规则

code 一般采取通用码和业务码相结合的方式进行。

通用码

通用码可以参考 http 协议的状态码，定义了最基本的一些情况，简单列举如下

• 200 请求成功
• 201 创建成功
• 400 错误的请求
• 401 未授权
• 403 无权限访问
• 404 无效的请求地址
• 500 服务器内部错误
• -1 业务错误，具体原因看 msg

除了上述的错误外，我们还会遇到更多和业务相关的错误。比如请求某个产品详情接口，没有传递 product_id 的「参数错误」，
或者需要传入 id 但是传入参数不是符合规定的数据类型（如：int）。 甚至是因为仓库产品不足，导致请求不能拿到产品列表需要提示的，等等。

在这种情况下，我们的通用码就不够看了，有个折衷的办法，就是返回统一的 code 码，如 -1。
然后在 msg 中对具体原因做说明。

对于出现错误排查原因，我们只需要看 code 为 500 和 -1 的请求，再结合 msg 即可排查

业务码

等等！仅仅靠 msg 来么，万一项目比较大，msg 近似，还怎么排查？有没有一种办法，根据 code 能快速定位到问题呢？

当然可以！

我们假设有如下业务模块：用户（User）、产品（Product）、评论（Comment）

我们可以对业务进行相关编码。

• User 01
• Product 02
• Comment 03

然后，我们在假设各个模块下，不同具体功能定义不同码，如：

• User 01
  • user/list 01
  • user/detail 02
• Product 02
  • product/list 01
  • product/detail 02
• Comment 03
  • comment/list 01
  • comment/detail 03

好了，目前我们根据业务拓展出了两层编码，如果后面有更多的业务层级，可以继续拓展下去。甚至是不同的错误，我们可以
映射出一张 code table，在编码过程中抛出。

至此，如果请求用户列表出错了，我们可以返回

{
  code: 0101,
  data: null,
  msg: "请求用户列表出错"
}

总结

定义返回值的意义在于约束多端开发，统一规范，大家可以根据自己的业务复杂程度和团队规模去指定符合自己的规范。
毕竟，其实好多团队也不是这么定义的，大家多去看看一些成熟平台定义的 API，完全可以参考，如：

• 百度地图
• 微信开发文档