在设计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 相结合
- 优点:依旧能保证标准化,可以处理兼容更多的业务场景。
- 缺点:客户端处理的复杂度高,需要根据业务场景做更多的判断选择