comm-framework/ProtoBufModule

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。

目录结构（源文件）

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

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 的作用（与网络实现配合）

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。

生成代码

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（强类型命令）。