无论是内部子系统对接还是外部接口对接,都会涉及通讯报文,为了统一、标准化报文结构,必须规约报文结构。
我们的系统架构,通讯方式主要有 REST 和 GRPC 两种,REST 是 JSON 格式,GRPC 是 ProtoBuff 格式。
字段 | 必选 | 类型 | 说明 |
---|---|---|---|
code |
是 | integer |
业务编码,0 表示成功,非 0 表示失败,具体说明看项目文档 |
info |
是 | string |
结果信息 |
data |
是 | object |
结果数据 |
对于列表格式的数据,其 data 结构体如下:
字段 | 必选 | 类型 | 说明 |
---|---|---|---|
count |
是 | integer |
总条数 |
totalPages |
是 | integer |
总页数 |
list |
是 | array |
列表数据 |
注意事项:
由于历史原因,可能有些接口的 data
, list
会返回 null 给前端,这是一种不好的设计,在后续的编码中必须禁止。对于没有数据的情况,返回空值(如 0, 空字符,空数组)而不是返回空(null, undefined 等)给前端。
{
"code" : 0,
"message" : "成功",
"data" : {
"count": 88,
"totalPages": 8,
"list":[
{
"name": "foo",
"id": 1
}
]
}
}
请求类必须用 Request 后缀
响应类必须用 Response 后缀
服务命名必须用 Service 后缀
响应类遵循以下的统一结构规范:
字段 | 必选 | 类型 | 说明 |
---|---|---|---|
code |
是 | int32 |
业务编码,0 表示成功,非 0 表示失败,具体说明看项目文档 |
info |
是 | string |
结果信息 |
注意事项:
由于历史原因,之前的项目没有规范约束,导致 info 和 msg 混用,今后统一使用 info。
为了兼容性和稳定性,已有的历史字段不做修改,新增的字段必须符合规范。
message CensorImageRequest {
bytes image = 1;
int32 terminal = 2;
string ext = 3;// 文件扩展名
}
message CensorImageResponse {
int32 code = 1;
string info = 2;
}
service CensorService {
rpc censorImage (CensorImageRequest) returns (CensorImageResponse);
}