HTTP 的业务错误码
Http 定义了 5大类别的码,这些码是通用的,其中只有 5XX
是表示服务的。各个系统的后端服务的用途/业务相差甚远,为数不多 5XX
远远不够用来表示可能出现的各种情况。于是,后端系统需要根据自己的业务制定业务级别的码,而 Http 的码,我们称其为协议级别的码。
业务码不属于 Http
协议的成员,是实践中的产物。它是定义在返回的消息实体中的,并没有固定的格式,但无非就是下面3种模块。
【级别(可选)】-【模块(必要)】-【具体编号(必要)】
码一般由 5~6 位整数组成,例子如下:
出参的格式主要有2种
{
"code":0, # 0 表示成功
"msg":"success" # success
"data":{
“name”:"鞋子",
"inventory":1000
}
}
{
"code":10001, # 码
"msg":"库存不足" # 描述信息
"data":{} # 业务实体
}
{
“name”:"鞋子",
"inventory":1000
}
{
"code":10001, # 码
"msg":"库存不足" # 描述信息
}
我本人是比较推崇第二种格式,因为大部分情况下都是成功,每次又要带上 code
,msg
没有实质性的作用,还占用带宽。另是的书写方面,每个接口把 code
,msg
带上会觉得很麻烦,不带上又怕不熟悉的人看了出错。比较友好规范的,我认为应该是由成功和失败2个独立的部分组成,正常的业务出入参放成功展示,失败的有专门的码表。
国际化的离不开码的,客户端指定语言到服务端去请求,当出错了服务端会根据码和语言找到对应的国际化语。
从上面图中我们发现,码不仅仅是客户端与服务端的交互,各个服务交互也需要约定的一套码。
一般国际化的系统中会有多份 xxx_lang.properties
,每一份代表一种语言的消息语。一般会转为 Unicode 编码进行存储(这个过程一般开发工具可以设置转),这样的处理可以规避不同开发环境下不同编码导致乱码。
接口有的是写给小组内部开发人员交流使用的,有的是对外开放给第三方的,是程序之间交互的桥梁。支付宝 / 微信 的接口是开发人员使用度比较广的第三方接口,我们经常会去他们的支付,相关的接口,下面着重看看他们的码是如何定义的。
1. 在独立的维护了
2. 业务接口详细列举了成功和的参数
1. 独立的维护了全局
2. 每个接口独立的
码是中很重要的一部分,它是 Http 协议码的补充,码并没有固定的格式要求,但是一般由 业务模块+模块下的详细信息 组成。此外,还需要根据场景定义场景下的消息符,可以根据客户端的语言返回相应语言的符。给的信息中也尽量避免过多展示底层实现细节,减小系统风险暴露。