85 lines
3.3 KiB
Markdown
85 lines
3.3 KiB
Markdown
# ProtoBufModule
|
||
|
||
本模块承载 **RPC 与业务消息的二进制契约**：所有 TCP 链路上传输的业务体都通过此处定义的 `protobuf` 生成 Java 类（包名 `com.huangzj.cmd.gen`）。
|
||
|
||
## 职责
|
||
|
||
- 维护 `src/main/protobuf` 下的 `.proto` 源文件。
|
||
- Maven `protobuf-maven-plugin` 在 `generate-sources` 阶段生成 Java 源码到 `target/generated-sources/protobuf/java`。
|
||
- **其它模块**（BaseModule、ServerModule、CrossModule）仅依赖本模块打出的 jar，不重复拷贝 `.proto`。
|
||
|
||
## 目录结构（源文件）
|
||
|
||
```text
|
||
src/main/protobuf/
|
||
└── serverProto/
|
||
├── cmd_rpc.proto # CmdRpcEnvelope、各 CTS/STC、Method 枚举
|
||
└── pb_service.proto # PbService（Service_1 ~ Service_4）
|
||
```
|
||
|
||
> 历史上独立的 `CrossProto` 已移除；跨服与区服共用 **`demo.cmd`** 包下的消息，通过 **service/method + CommandSource** 在 Java 侧区分语义。
|
||
|
||
## 网络层核心消息：`CmdRpcEnvelope`
|
||
|
||
```protobuf
|
||
message CmdRpcEnvelope {
|
||
uint32 service_id = 1;
|
||
uint32 method_id = 2;
|
||
bytes payload = 3; // 具体 CTS 的序列化字节
|
||
int32 cross_ret = 4; // 预留/透传
|
||
uint32 link_seq = 5; // 区服↔跨服长连接多路复用序号（客户端 TCP 可为 0）
|
||
}
|
||
```
|
||
|
||
### `link_seq` 的作用（与网络实现配合）
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Z as 区服 CrossTcpClient
|
||
participant X as 跨服 TCP
|
||
Note over Z,X: 单条 TCP 上可能同时存在多帧在途
|
||
Z->>X: 请求 A (link_seq=101)
|
||
Z->>X: 请求 B (link_seq=102)
|
||
X-->>Z: 响应 B (link_seq=102)
|
||
X-->>Z: 响应 A (link_seq=101)
|
||
```
|
||
|
||
- 区服在 **`CrossTcpClient`** 内为每次 `roundTrip` / 注册 / 心跳分配 **非 0** 的 `link_seq`。
|
||
- 跨服命令通过 **`AbstractTypedPbCommand`** 回包时 **原样带回** 请求信封中的 `link_seq`，以便客户端把响应与 `CompletableFuture` 对应。
|
||
|
||
## 服务与方法枚举
|
||
|
||
| PbService | 用途 |
|
||
|-----------|------|
|
||
| Service_1 | 路径 1 示例（Echo） |
|
||
| Service_2 | 跨服业务 Method2（`CrossForward*`） |
|
||
| Service_3 | 路径 3 区服对客户端暴露的中转接口 |
|
||
| Service_4 | **链路控制**：Register、Heartbeat（仅区服→跨服长连接上使用） |
|
||
|
||
`Service4_Method`：`Register`、`Heartbeat`，载荷分别为 `CrossLinkRegisterCts/Stc`、`CrossLinkHeartbeatCts/Stc`。
|
||
|
||
## 业务消息（与路径对应）
|
||
|
||
- **路径 1**：`CmdEchoCts` / `CmdEchoStc`。
|
||
- **路径 2（客户端侧）**：`CrossProxyCts` / `CrossProxyStc`（区服内会转为 `CrossForward*` 再发往跨服）。
|
||
- **路径 3**：客户端 payload 使用 **`CrossForwardCts`** 形态（与跨服 Service_2/Method2 一致），信封为 Service_3/Method3。
|
||
- **跨服 Service_2/Method2**：`CrossForwardCts` / `CrossForwardStc`。
|
||
|
||
## 生成代码
|
||
|
||
```bash
|
||
cd ProtoBufModule
|
||
mvn -q generate-sources
|
||
# 或使用 genpb.bat（Windows，会探测 Maven）
|
||
```
|
||
|
||
生成物加入 `ProtoBufModule` jar，依赖方编译时自动可见。
|
||
|
||
## 扩展约定
|
||
|
||
新增 RPC 时建议：
|
||
|
||
1. 在 `pb_service.proto` 增加 `PbService` 枚举值（若新服务号）。
|
||
2. 在 `cmd_rpc.proto` 增加 `ServiceX_Method` 与 CTS/STC `message`。
|
||
3. 执行 `generate-sources` 后，在 **BaseModule** 侧通过 `@Cmd` + `AbstractTypedPbCommand` 或 `GameCommand` 实现逻辑，并由 **`ProtoRegistryAutoConfigurer`** 自动注册 `ProtoInfo`（强类型命令）。
|