# 通讯报文结构设计

## 前言

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

我们的系统架构，通讯方式主要有 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 等)给前端。

#### 示例
  
```json
{
  "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**。

为了兼容性和稳定性，已有的历史字段不做修改，新增的字段必须符合规范。

#### 示例

```protobuf
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);
}
```