## 说明

> 本仓库用于定义`客户端<->服务端`间的通信协议。<br />
> SDK业务使用`http(s)`进行连接。<br />
> 游戏业务使用`tcp/udp`进行连接。`protobuf3`作为流序列化工具，`pomelo`协议作为数据包的格式(详见[pomelo.md](pomelo.md))。

## 适用范围

- 客户端工程师
- 服务端工程师
- 压力测试工程师

## SDK协议业务

> SDK为玩家提供帐号身份服务。产品上线后，根据发行情况会进行多种SDK的接入。<br />
> 根据情况,每个SDK会输出多个安装包。我们定义`pid`参数做为安装包的唯一标识。<br />
> 在开发阶段，本游戏提供了一个`开发模式sdk`用于当前开发阶段使用。<br />

### SDK处理流程

- 1.启动客户端安装包，并加载当前SDK库。
- 2.用户通过SDK的`帐号注册`功能进行帐号注册。
- 3.用户输入`帐号信息`进行SDK帐号登录，并返回`SDK的用户标识(sdk user token)`等参数。
- 4.客户端请求`帐号验证接口`，验证`SDK的用户标识(sdk user token)`参数，成功后并返回`游戏token(game token)`。
- 5.用户点击区服列表，连接对应的`网关地址`，进行游戏登录、玩家创建、玩家登录等操作。

### 通用响应格式

| 参数名     | 类型     | 必填  | 描述                |
|:--------|:-------|:----|:------------------|
| code    | int    | 是   | 状态码 0.正常码,其他值为错误码 |
| message | string | 是   | 消息文本              |
| data    | string | 否   | 业务响应数据            |

- 响应格式：`JSON`
- 正常的响应： `{"code":0,"message":"成功","data":[]}`
- 错误的响应： `{"code":100007,"message":"平台帐号验证失败","data":[]}`

### 接口地址

- dev环境地址：http://127.0.0.1/
- prod境地址：~~http://xxx.com/~~

### 什么是`pid`?

- `pid`可以理解为 `package unique id`，给每个对外发布的安装包配置唯一的编号。
- `pid`统一由`运营人员`进行分配。
- `SDK`与`pid`的关系是一对多的关系。每个分配出去的`pid`必然归属于一个`SDK`。例如：pid=2122150归属于xx游戏的Q1SDK。

### API-01 开发模式SDK帐号注册

本sdk用于开发阶段使用，需首先接入。客户端可以做一个临时的界面用于帐号注册、帐号登录。正式上线后通过打包系统输出其他sdk的安装包。

- 接口地址: http://127.0.0.1/dev/register
- 请求方式：GET
- 请求参数：

| 参数名      | 类型     | 必填  | 描述  |
|:---------|:-------|:----|:----|
| account  | string | 是   | 帐号名 |
| password | string | 是   | 密码  |

- 响应结果: 通用格式

### API-02 帐号验证接口

该接口为通用帐号验证接口，适用于所有SDK。 每个SDK的请求参数都会稍有不一样，但`响应结果`为统一的`json`结构。

- 接口地址: http://127.0.0.1/login
- 请求方式：GET

#### API-02-01 开发模式SDK请求参数

请求示例：http://127.0.0.1/login?pid=2188001&account=aaaa&password=bbbb

| 参数名      | 类型     | 必填  | 描述  |
|:---------|:-------|:----|:----|
| pid      | string | 是   | 包id |
| account  | string | 是   | 帐号名 |
| password | string | 是   | 密码  |

#### API-02-02 xxSDK请求参数
- TODO 


## 游戏协议业务

游戏协议业务的定义描述在本仓库的`*.json`和`*.proto`中。

`json`文件用于描述每条协议的详情，客户端可根据该文件生成客户端协议代码。

`proto`文件用于定义每条消息的结构。

- `Request/Response` 两者为配对的消息，有Request必有Response
- `Notify` 指客户端推送消息给服务器，服务器不用回复
- `Push` 指服务器推送消息给客户端，客户端不用回复

### 示例介绍

以下示例介绍了游戏业务的首条通信协议：`登录游戏服`。

```json
[
  {
    "enable": true,
    "name": "[请求]登录游戏服(首条)",
    "route": "gate.user.login",
    "request": "LoginRequest",
    "response": "LoginResponse",
    "notify": "",
    "push": "",
    "desc": "游戏服登录，连接游戏服的第一条协议"
  }
]
```

- `enable` 是否启用该条协议
- `name` 协议名称
- `route` 路由名称
- `request` request类型请求, `LoginRequest`为pb结构
- `response` response类型请求，`LoginResponse`为pb结构
- `notify` 客户端请求`notify`类型的消息，不用等待返回的消息
- `push` 服务端推送`push`类型的消息
- `desc` 协议描述