team-standard/通讯报文结构设计.md

通讯报文结构设计

前言

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

我们的系统架构，通讯方式主要有 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);
}