框架介绍

Wukong 是一个基于 协程+线程混合模型 的 C++ 游戏后端框架，核心设计理念是：

• 同步风格编程：用协程实现异步性能，代码写起来像同步调用
• 线程固定、协程从属：同一线程内协程共享资源无需加锁
• 无锁高性能：大量使用无锁队列
• Nexus 替代 ZooKeeper：内置服务注册发现，不再依赖外部协调服务

                        ┌─────────┐
                        │  Nexus  │  注册发现中心
                        └────┬────┘
                               │ 服务上下线通知
          ┌────────────────────┼──────────────────────┐
          ▼                    ▼                      ▼
   ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
   │  Front   │  │ Gateway  │  │  Lobby   │  │  Scene   │
   │ 前置转发  │  │  网关服   │  │  大厅服  │  │  场景服   │
   └──────────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘
                      │             │              │
              ┌───────┴───────┐    │              │
              ▼               ▼    ▼              ▼
         ┌──────────┐  ┌──────────┐  ┌──────────┐
         │  Login   │  │ Record   │  │  Battle  │
         │  登录服   │  │  记录服   │  │  战斗服   │
         └──────────┘  └────┬─────┘  └──────────┘
                            │
                    ┌───────┴───────┐
                    ▼               ▼
              ┌──────────┐   ┌──────────┐
              │  Redis   │   │  MySQL   │
              │  缓存     │   │  落地库   │
              └──────────┘   └──────────┘

各服务职责

各模块职责一览

模块	类型	核心职责	解决的问题
share	共享库	协程、RPC、网络层、Agent系统、事件、日志、DB连接池	框架基础设施
utils	共享库	Redis/MySQL操作封装、时间链表、JSON、Proto工具	通用工具
nexus	独立进程	服务注册、发现、关注关系推送	替代ZooKeeper，服务治理
gateway	独立进程	客户端接入、消息路由、断线重连、顶号	客户端与后端的桥梁
login	独立进程	账号认证、创角、进入游戏、Passport签发	登录流程
lobby	独立进程	玩家对象管理、心跳、存盘、消息处理	玩家业务逻辑主载体
scene	独立进程	场景管理、跨进程场景切换	游戏场景逻辑
record	独立进程	数据缓存、脏写、时间轮落盘	数据持久化
battle	独立进程	帧同步战斗、KCP通信、快照对齐	实时战斗
front	独立进程	TCP透明转发、限流	前置代理保护
opctrl	独立进程	HTTP运营接口、GM命令	运营管理
proto	协议定义	Protobuf消息和RPC服务定义	通信协议
tools	代码工具	Go代码生成器	自动化数据类生成
sql	数据库脚本	user/role表结构	数据库Schema

设计哲学

1. 同步风格编程 + 协程性能

传统游戏服务器为了高性能，大量使用异步非阻塞（回调、状态机），导致逻辑碎片化、难以维护。Wukong 用协程解决了这个矛盾：

// 写起来像同步代码：
stub->kick(controller, request, response, nullptr);  // 这行会"卡住"
// 但底层协程自动挂起，不阻塞线程，等RPC响应回来后恢复
if (controller->Failed()) { /* 处理失败 */ }
int result = response->value();  // 直接拿结果

关键点：协程在 RPC 等待时挂起，线程去执行其他协程；响应回来后协程恢复继续执行。性能接近异步，代码像同步一样直观。

2. 线程固定 + 协程绑定

• 线程数量在初始化时固定配置（收线程池、发线程池）
• 协程从属于线程，同一线程内的协程共享资源时不需要加锁
• 这是一种"用协程级别的并发替代线程级别的并发"的思路

3. 无锁优先

• 不依赖系统互斥锁
• 使用无锁队列（Co_MPSC_NoLockQueue）等无锁数据结构
• 配合"协程绑定线程"模型，大部分场景天然无竞争

4. Redis 作为分布式协调中心

Wukong 大量使用 Redis 做分布式协调，而非引入 etcd/ZooKeeper 等重型组件：

• Session/Location 管理：玩家在哪个 Gateway/Lobby/Record 上
• Passport 一次性令牌：登录票据
• 分布式锁：存盘锁、创角锁
• Pub/Sub：跨服事件广播、热更新通知
• Lua 脚本：保证复杂操作的原子性

5. 委托模式扩展

各模块通过 Delegate 接口提供扩展点，业务层通过设置回调函数实现自定义逻辑，框架与业务解耦。

学习目标

第一阶段：理解基础模型（1-2 周）

目标：掌握协程驱动的同步编程模型和框架核心概念

1. 阅读 README.md 和 const.h
   • 理解服务器类型枚举（SERVER_TYPE_NEXUS, SERVER_TYPE_GATE 等）
   • 理解消息 ID 编码规则：高 16 位 = 目标 ServerType，低 16 位 = 功能号
2. 理解协程模型
   • 阅读 GameObject 的三个静态协程方法：heartbeatRoutine, syncRoutine, updateRoutine
   • 理解 Cond 条件变量在协程中的用法（类似信号量，协程挂起/唤醒）
   • 关键：同一线程内协程不产生竞争，无需加锁
3. 跑通 Demo
   • 阅读 demo/ 下的代码：demo/client/, demo/scene/, demo/generate/
   • 理解 DemoGameObject 如何继承基类、实现钩子方法
   • 理解 MessageHandler 如何注册消息

第二阶段：核心模块深入（2-3 周）

目标：掌握玩家对象生命周期和消息流

1. GameObject/LobbyObject 生命周期
   • 从 loadRole → onStart → enterGame → onEnterGame → update → leaveGame → onOffline → stop → onDestory
   • 重点看 GameObjectManager::loadRole() 流程
2. 消息处理机制
   • registerMessage() 注册 → handleMessage() 分发 → 协程/非协程执行
   • MessageTarget 的 wait_messages_ 等待队列机制
   • 阅读 demo/scene/message_handler.cpp 看实际例子
3. Agent 通信体系
   • AgentManager 如何连接 Nexus
   • Agent::resetStubs() 如何在服务变更时重建连接
   • 以 LobbyAgent::loadRole() 为例理解 RPC 调用流程
4. 数据持久化
   • RecordObjectData 的 dirty_map_ 脏标记机制
   • buildSyncDatas() → 定时 sync() → Redis → MySQL
   • 理解 DemoRoleBuilder 如何生成数据构建代码

第三阶段：扩展开发（2-3 周）

目标：学会在框架上扩展业务功能

1. 实现自定义 GameObject
   • 继承 LobbyObject 或基类 GameObject
   • 实现 onStart(), onDestory(), onEnterGame(), onOffline()
   • 在 onUpdate() 中实现周期逻辑
2. 实现消息处理
   • 继承 MessageHandler 风格的类
   • 在 registerMessages() 中注册消息
   • 实现处理函数：void Handle(shared_ptr, uint16_t tag, shared_ptr)
3. 场景系统开发
   • 继承 Scene 基类实现 update(), onEnter(), onLeave(), onDestory()
   • 继承 SceneRole 实现角色数据
   • 理解 4 种场景类型：单人副本 / 多人副本 / 队伍副本 / 世界场景
4. 设计配置开发
   • 继承 DesignConfigTable 实现 designName() 和 onParse()
   • 通过 DesignConfigHub 注册和加载

第四阶段：高级特性（持续学习）

目标：掌握生产级特性

1. 帧同步战斗系统
   • 阅读 battle/ 下 BattleRoom, BattleRoomManager, BattleServer
   • 理解 GameCore 模拟器、帧输入、快照广播
   • KCP 连接管理
2. 全局事件系统
   • GlobalEventEmitter 跨服事件分发
   • 通过 Redis Pub/Sub 实现
3. 分布式锁
   • share/lock/distribute_lock 实现
4. Lua 热更新
   • message_hotfix_manager 消息热修复
   • demo/hotfix/ 示例
5. 分区分服与合服
   • LoginHandlerMgr 中的 serverGroupData_ 管理
   • 大区、分区、滚服、合服逻辑