http请求响应代码决定接口是否可以调用,而具体的报文code意味着这个服务的逻辑是否正常运行。以下讨论的是报文返回的规范。
1. JSON 格式
{
"code" : "",
"message" : "",
"data" : Object,
"extra" : Object,
"timestamp" : Time
}
2. 具体说明
2.1 code
2.1.1 描述
指错误代码,特定的错误代码就像程序中定义的 Exception 一样,具有标志性。需要告诉对方,那些是需要提示的异常,那些是不可预知的异常,都需要在此进行定义与规范。
2.1.2 定义
通常定义 code 需要区分模块。0(0000000) 代表成功其他则代表异常。而异常又是区分提示性质和全局异常。如:
系统 提示/异常 模块 异常码
| | | |
AA (0/1) (000~999) (000~999)
- 系统:使用2个字母表示A-Z(676个组合)
- 提示/异常:区分需要提示的异常,比如说参数缺失,输入异常等。有部分异常需要抛出到前端,有些需要服务自行消化的。
- 模块:一个系统中的模块(999个组合)
- 异常码:每个模块中的异常码(999个组合)
其中需要划分通用异常码区域(指定模块是 001 ),主要用于各个模块整合的时候定义通用的错误。比如登陆账号已经退出(可能服务与服务之间感知时间不一样,导致数据出现异常)。整合到前端的时候可以更好处理相关的跳转逻辑。如:
系统 提示/异常 模块 异常码
| | | |
AA (0/1) 001 (000~999)
2.2 message
主要提示性的消息,这里可以依据浏览器的语言做国际化处理。
2.3 data
具体使用的数据,请求成功后的话,此处是有数据的。
2.4 extra
更多用于此接口(data)已经提供到外部使用,但是在不增加新接口与修改接口的情况下需要对接口的数据格式进行扩展,可以将数据写到这里。
2.5 timestamp
请求时间