通讯报文结构设计.md 2.6 KB

通讯报文结构设计

前言

无论是内部子系统对接还是外部接口对接,都会涉及通讯报文,为了统一、标准化报文结构,必须规约报文结构。

我们的系统架构,通讯方式主要有 REST 和 GRPC 两种,REST 是 JSON 格式,GRPC 是 ProtoBuff 格式。

目的

  • 服务端统一报文结构接口,客户端更加标准、简洁,程序更加工程化

规约

JSON

规范

字段 必选 类型 说明
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
      }
    ]
  }
}

ProtoBuff

规范

  • 请求类必须用 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);
}