趣说API HTTP 状态码的使用

在设计API HTTP 状态码的时候，我们总能听到两种声音：
第一种，也是大家最常用的：

所有接口的状态码都返回 200，然后在自定义错误码：

# 正确响应
{
  "code: 200,
  "message": "success",
  "data": {
    "id": ...,
    ...
  }
}
# 错误响应
{
  "code: 1001, // 自定义错误类型
  "message": "error message",
  "data": {}
}

另一种，Rest API,仅使用HTTP状态代码：

# 正确响应
HTTP/1.1 200
Content-Type: application/json
{
    "id": ...,
    ...
}

# 错误响应
HTTP/1.1 401 Unauthorized
{
  "message": "Bad credentials"
}

更多的错误码规范可以直接从 HTTP Status Code 查看。

为什么说是两种声音，其实现在基本规范的话都会直接选择第二种，基本上，Github的

Github API v3以及现在普遍后端框架的设计都对于Rest API 有着更好的支持。
所以上面声音的争执似乎存在与前后端的更多些。

补充一下 Github v4 版本已经开始使用 GraphQL了，GraphQL 是一种查询语言，相比于Rest API的设计，现在国外比较喜欢和流行GraphQL ，但好像国内还并未听说有过多的使用。

说一下两者的优缺点吧，
第一种：

• 优点：客户端仅需要处理作为 json字符串的响应主体并忽略状态。
• 缺点：标准化低。

第二种：

• 优点：标准化高，客户端仅需要处理作为json字符串的响应主体并忽略状态。
• 缺点：业务复杂度高时的使用场景使用不足。

而结合两种优缺点，现在许多人开始有了第三种方式：
HTTP Status 与Json body 相结合

• 优点：依旧能保证标准化，可以处理兼容更多的业务场景。
• 缺点：客户端处理的复杂度高，需要根据业务场景做更多的判断选择

参考资料

Github API v3
HTTP Status Code
dingo-api 错误响应
Github v4