UnityAI/modules/frameworks/网络系统.md

网络系统

分类

• 核心框架

目的

提供 WebSocket 连接、protobuf 消息收发、消息 ID / route 映射和错误响应处理。

---

核心路径

• protobuf 源：GoogleProtobufNetwork/
• 生成输出：Assets/Game/GameHFScripte/CopyToHF/Network/
• WebSocket：Assets/Game/GameHFScripte/GameFunction/WebSocket/

---

核心类

类	职责
HFSeverManager	网络管理器单例
WSSession	WebSocket 会话
HFM_Socket_WS	WebSocket 底层连接
HFWebSocket_Manager_AutoMsgMap	自动生成消息映射
HFNetWorkMsgIdMap	网络消息 ID 映射
MessagePage	数据包编解码

---

C2S 发送链路

IMessage.Dispatch()
  -> HFSeverManager.Instance.SendMsg(message)
  -> HFSeverManager.OnAuto_OnGetProtocNo(message)
  -> HFSeverManager.OnAuto_OnGetRoute(Network_MsgId)
  -> m_Session.SendMessage(protoNo, route, PacketType.Data, Request, message)

IMessage.Dispatch() 定义在 Assets/Game/GameHFScripte/GameFunction/WebSocket/Extends/HFServer_Extend.cs。

---

WebSocket 连接流程

登录管理器.ConnectServer
  -> HFSeverManager.Connect(MainConnect, WebSocket, ip, port, token)
  -> WSSession.Connect
  -> HFM_Socket_WS.Connect
  -> Handshake -> HandshakeAck -> 连接成功回调

---

S2C 收包和派发

WSSession.ReceiveMessages(PacketType.Data)
  -> MessagePage.Decode(packet.Body)
  -> Response.MessageId / Push.Route -> Network_MsgId
  -> HFSeverManager.OnAuto_OnMergeFrom(msgid, body)
  -> protobuf Parser.ParseFrom
  -> 反射创建 HFEvent_STC_{MessageTypeName}
  -> 写入 Request / ErrorCode
  -> AbsHFEventArg<enHFSTCEvent>.Dispatch()
  -> HFEventManager.Instance.STCEvent.Dispatch(arg)

---

自动生成映射

• HFWebSocket_Manager_AutoMsgMap.cs：提供 OnAuto_OnGetProtocNo、OnAuto_OnGetRoute、OnAuto_OnMergeFrom、msrDicRouteToMsg、S2C/C2S 类型字典。
• HFNetWorkMsgIdMap.cs：为 protobuf partial class 标记 [HFNetworkMsg(...)]。

---

使用规则

• 新增协议先改 .proto、msg.proto、route.txt。
• 不手动修改生成输出。
• 不硬编码 route 或数字 msgId。
• UI 监听 S2C 必须在 OnClose 移除。
• 错误响应会触发 HFEvent_ErrorCode。

---

协议变更清单

1. 修改 .proto 和 msg.proto。
2. 登记 msgId / route（如 route.txt 或对应生成配置）。
3. 通过生成器重新生成 C# 代码到 Assets/Game/GameHFScripte/CopyToHF/Network/。
4. 检查 HFNetWorkMsgIdMap.cs / HFWebSocket_Manager_AutoMsgMap.cs 是否同步。
5. 更新业务入口和监听。
6. 编译 GameHF 并运行连接/收发测试。

验证

• 构建 GameHF.csproj。
• 在支持服务器的运行环境中登录、收发 C2S/S2C 消息。
• 确认 HFEvent_STC_* 正确派发并在 OnClose 时移除监听。
• 验证错误码事件 HFEvent_ErrorCode 触发路径。

当前状态

• 待验证

---

相关模块

• 事件系统
• 数据/配置框架

---

文档关联

当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。

文档	关联原因
modules/模块索引.md	模块索引是项目知识总入口
modules/frameworks/事件系统/README.md	S2C 消息派发为 STC 事件
modules/frameworks/数据配置框架.md	配置表与网络消息可能联动
rules/10-架构说明.md	架构说明定义总体分层和依赖方向
rules/30-模块登记规则.md	模块登记规则定义分类和状态口径