API 接口的响应参数应该如何设计，错误码、错误信息应该怎么返回，这篇文章给你解答。

典型响应格式

响应参数通常都需要有一个比较固定的格式，以便客户端解析数据，判断是否成功。
一般我们都会包含一个错误码来表示是否成功，然后再包含一个错误信息，来说明具体的错误原因
典型的结构如下：

1
2
3
4
5
{
	"code": 0,
	"msg": "这里是错误原因说明",
	"data": {} // 业务数据
}

错误码的设计

可能有人会说，http 已经有 status code 了，我们没必要额外的定义一个错误码
我们先来看下 http 的 status code 有哪些：
200 （成功） 服务器已成功处理了请求。 通常，这表示服务器提供了请求的网页。
301 （永久移动） 请求的网页已永久移动到新位置。
403 （禁止） 服务器拒绝请求。
404 （未找到） 服务器找不到请求的网页。
500 （服务器内部错误） 服务器遇到错误，无法完成请求。

从上面看得出，status code 应该理解为状态码，表示 http 的请求状态。
而我们的业务逻辑应该有自己独立的一套状态码，独立区分开来更加的灵活方便，更加利于扩展。

回到上面的错误码 code，我们可以用0来表示成功状态，小于0的值来表示错误状态，大于0的值用来表示成功，但是有额外步骤，例如：
1 注册成功，但是需要完善个人资料
5 登录成功，但是需要绑定手机号
0 成功
-1 参数不全
-5 错误格式错误
-10 手机号格式错误
-15 价格只能是数字

错误码的数字，不建议使用连续的数字，最好是间隔5个数字，这样是为了更好的扩展，方便以后如果中间需要插入一个新的判断逻辑时，我们可以使用保留的错误码，以便连续相关的逻辑能有相近的错误码。
举个例子，就按上面我们列举的错误码，已经有了一个手机号格式错误的错误码 -10，某天，我们需要增加限制只能使用联通的手机号，那我们可以使用 -10 附近的保留错误码，这样我们就可以把一些逻辑相近的代码错误码也相近。

总结下就是：用0表示正确，大于0表示正确但是需要额外处理，小于0表示错误；错误码应该间隔使用，预留一些后面使用。

业务数据

业务数据可以固定使用一个 data 字段，例如：

1
2
3
4
5
{
	"code": 0,
	"msg": "ok",
	"data": {"list": ["zhangsan", "lisi"], "count": 10}
}

使用固定字段的好处是格式统一，方便客户端读取数据，但是增加了层次结构，如果不想要那么多层次的话，也可以这样：

1
2
3
4
5
6
{
	"code": 0,
	"msg": "ok",
	"list": ["zhangsan", "lisi"],
	"count": 10
}

省略字段

为了方便客户端解析和判断，一般都会把响应数据设计成我们前面提到的固定格式。
如果想要更加简洁，在某些情况，我们可以省略某些字段
例如，成功的情况，我们可以把 code 和 msg 字段都省略掉，那客户端怎么判断是否有错呢？
可以这么判断：
存在 code 并且是小于0，表示有错误。
不存在 code 时，默认是正确的。
存在 code 并且是大于0，表示正确但是需要额外处理。

举例， 失败情况：

1
2
3
4
{
	"code": -1,
	"msg": "参数不全"
}

正确情况

1
2
3
{
	"data": {} // 业务数据
}

需要额外处理

1
2
3
4
{
	"code": 5,
	"msg": "需要完善个人资料"
}

好了，以上就是响应数据的格式设计，具体情况可以根据自己的项目来决定使用，如果是对外的公开接口，建议是使用固定的格式并且不省略字段，这样更加清晰明了。