108 lines
4.5 KiB
Markdown
108 lines
4.5 KiB
Markdown
|
# BaseModule
|
|||
|
|
|
|||
|
|
**公共运行时库**：被 `ServerModule` 与 `CrossModule` 依赖。包含 **Netty TCP 帧编解码**、**CmdRpc 分发管线**、**Proto 元数据注册表**、**Spring 命令扫描** 以及与跨服调用相关的 **`CrossRpcInvoker` 接口**。
|
|||
|
|
|
|||
|
|
本模块 **不是** 可执行 Spring Boot 应用；随区服或跨服进程一起加载。
|
|||
|
|
|
|||
|
|
## 网络分层（逻辑）
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
flowchart TB
|
|||
|
|
subgraph TCP["TCP 字节流"]
|
|||
|
|
F["一帧: 4B length + body"]
|
|||
|
|
end
|
|||
|
|
subgraph Net["BaseModule / net & frame"]
|
|||
|
|
D["LengthPrefixedProtobuf 解码"]
|
|||
|
|
H["CmdRpcTcpFrameHandler"]
|
|||
|
|
end
|
|||
|
|
subgraph Cmd["BaseModule / cmd"]
|
|||
|
|
CD["CmdRpcChannelDispatch"]
|
|||
|
|
PR["ProtoRegistry → ProtoInfo"]
|
|||
|
|
PC["ProtoCommandReflect 解析 CTS / newBuilder STC"]
|
|||
|
|
DP["CmdRpcDispatch → GameCommand"]
|
|||
|
|
end
|
|||
|
|
F --> D --> H --> CD
|
|||
|
|
CD --> PR
|
|||
|
|
CD --> PC
|
|||
|
|
CD --> DP
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 1. 帧格式：`LengthPrefixedProtobuf`
|
|||
|
|
|
|||
|
|
- **编码**：`LengthPrefixedProtobuf.encodeMessage(alloc, CmdRpcEnvelope)` — 先写 **大端 int32 长度**，再写 `CmdRpcEnvelope.toByteArray()`。
|
|||
|
|
- **解码**：`newTcpFrameDecoder()` 返回 Netty 解码器，攒满一帧后向 pipeline 下游抛出 **一条 ByteBuf（仅 body）**。
|
|||
|
|
|
|||
|
|
这样 **区服客户端 TCP** 与 **跨服 TCP** 与 **区服连跨服的 Outbound** 三者 **帧格式一致**，仅 IP/端口与 `CommandSource` 不同。
|
|||
|
|
|
|||
|
|
## 2. 入站处理：`CmdRpcTcpFrameHandler`
|
|||
|
|
|
|||
|
|
- 读取一帧 `byte[]`，调用 **`CmdRpcChannelDispatch.dispatch(...)`**。
|
|||
|
|
- 将返回的 **`CmdRpcEnvelope`** 再次 **长度前缀编码** 写回对端。
|
|||
|
|
- `linkSource` 由构造时注入：`Client_TCP`（区服接客户端）或 `CROSS_TCP`（跨服接入站）。
|
|||
|
|
|
|||
|
|
**注意**：默认在 **Netty IO 线程** 上执行命令；若 `roundTrip` 同步调跨服会阻塞该连接上的 IO，Demo 场景可接受，生产需评估线程模型。
|
|||
|
|
|
|||
|
|
## 3. 分发核心：`CmdRpcChannelDispatch`
|
|||
|
|
|
|||
|
|
步骤简述：
|
|||
|
|
|
|||
|
|
1. `CmdRpcEnvelope.parseFrom(raw)`。
|
|||
|
|
2. `protoRegistry.resolve(linkSource, serviceId, methodId)` → 可选的 **`ProtoInfo`**。
|
|||
|
|
3. 若存在 `ProtoInfo`：**解析 payload 为 CTS**、**创建 STC 的 `Builder`**（网络层职责，命令内只填字段）。
|
|||
|
|
4. 构造 **`CommandContext`**（含 `ChannelHandlerContext`、`CrossRpcInvoker`、解码结果等）。
|
|||
|
|
5. **`CmdRpcDispatch.dispatchEnvelope(in, lookup, cctx)`** → 执行具体 **`GameCommand`**。
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
flowchart LR
|
|||
|
|
IN[CmdRpcEnvelope in]
|
|||
|
|
PI{ProtoInfo 存在?}
|
|||
|
|
DEC[解码 CTS + STC Builder]
|
|||
|
|
RAW[decoded=null 由命令自处理]
|
|||
|
|
EXE[GameCommand.execute]
|
|||
|
|
OUT[CmdRpcEnvelope out]
|
|||
|
|
IN --> PI
|
|||
|
|
PI -->|是| DEC --> EXE
|
|||
|
|
PI -->|否| RAW --> EXE
|
|||
|
|
EXE --> OUT
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 4. 命令模型
|
|||
|
|
|
|||
|
|
| 类型 | 说明 |
|
|||
|
|
|------|------|
|
|||
|
|
| `GameCommand` | `execute(CommandContext, CmdRpcEnvelope)`，完全自控 payload。 |
|
|||
|
|
| `AbstractTypedPbCommand<C, B>` | 依赖 `ProtoInfo`；`run(ctx, cts, stcBuilder)`；回包信封 **复制** `service/method/cross_ret/link_seq`。 |
|
|||
|
|
|
|||
|
|
### `CommandSource` 与注册
|
|||
|
|
|
|||
|
|
- `@Cmd(source, serviceId, methodId)` 标注在命令类上。
|
|||
|
|
- **`SpringGameCommandRegistry`**：按 Spring 容器里 `GameCommand` Bean 扫描，**只收录** `source` 属于当前进程配置集合的命令（区服只收 `Client_TCP`，跨服只收 `CROSS_TCP`）。
|
|||
|
|
|
|||
|
|
## 5. `ProtoRegistry` 与自动注册
|
|||
|
|
|
|||
|
|
- **`ProtoRegistry`**：`register(ProtoInfo)` / `resolve(source, serviceId, methodId)`。
|
|||
|
|
- **`ProtoRegistryAutoConfigurer`**（`SmartInitializingSingleton`）：扫描带 `@Cmd` 的 `GameCommand`，若继承 **`AbstractTypedPbCommand`**，则从泛型推断 **CTS / STC 类型** 并注册 **`ProtoInfo`**。
|
|||
|
|
- **未** 继承强类型基类的命令（如路径 3 中继）**不注册** `ProtoInfo`，由命令自行处理 payload。
|
|||
|
|
|
|||
|
|
## 6. `CrossRpcInvoker`
|
|||
|
|
|
|||
|
|
- 接口方法：`CmdRpcEnvelope roundTrip(CmdRpcEnvelope request)`。
|
|||
|
|
- **ServerModule** 中由 **`CrossTcpClient`** 实现：维护至跨服的 **长连接**、`link_seq` 多路复用、注册与心跳。
|
|||
|
|
|
|||
|
|
区服业务命令（路径 2/3）通过 **`CommandContext.crossRpc()`** 拿到该实例，向跨服发 **`CrossForward*`** 对应的信封。
|
|||
|
|
|
|||
|
|
## 7. 依赖说明
|
|||
|
|
|
|||
|
|
- **Spring Context**（`@Component` 等）、**Netty**、**protobuf-java**、**slf4j-api**、**Lombok**（可选）。
|
|||
|
|
- 生成的 proto Java 类来自 **ProtoBufModule**。
|
|||
|
|
|
|||
|
|
## 包结构（主要）
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
com.huangzj.base
|
|||
|
|
├── cmd # 分发、上下文、注册表、Proto 反射、CrossRpcInvoker
|
|||
|
|
├── frame # 长度前缀、Buf 工具
|
|||
|
|
├── net # CmdRpcTcpFrameHandler
|
|||
|
|
└── spring # SpringGameCommandRegistry、其它 Spring 辅助
|
|||
|
|
```
|