浏览器  --请求-->  服务器
浏览器 <--响应--  服务器
        （连接断开）

游戏客户端  <=======长连接=======>  游戏服务器
             （持续保持连接，可能几小时）

你需要自己实现：
├── 网络层
│   ├── TCP/UDP/WebSocket 连接管理
│   ├── 心跳检测（判断玩家是否掉线）
│   ├── 断线重连处理
│   └── 粘包拆包（TCP是流，没有消息边界）
├── 业务层
│   ├── 消息路由（怎么找到处理这条消息的代码）
│   ├── 线程模型（怎么并发处理又不冲突）
│   ├── 玩家会话管理
│   └── 状态同步
├── 分布式
│   ├── 服务发现（新服务器启动怎么被找到）
│   ├── 负载均衡（请求分给哪台服务器）
│   ├── 跨服通信（不同服务器之间怎么通信）
│   └── 容错处理（一台挂了怎么办）
└── 性能优化
    ├── 内存管理
    ├── 垃圾回收优化
    ├── 批量处理
    └── 零拷贝

// 传统方式：你需要手动写这些
ServerSocket server = new ServerSocket(8080);
while (true) {
    Socket client = server.accept();
    // 处理粘包拆包
    // 处理心跳
    // 处理断线重连
    // 处理协议编解码
    // ... 大量底层代码
}

// 传统方式：你需要手动加锁
public synchronized void buyItem(User user, int itemId) {
    // 玩家买道具，扣金币、加物品
    // 但 synchronized 会导致性能瓶颈
}

使用 ioGame 后：
├── 网络层：框架自动处理，你的业务代码零感知
├── 并发控制：通过线程模型自动保证，你不需要加锁
├── 分布式：内置服务发现，启动即注册，无需外部中间件
└── 业务开发：写普通 Java 方法就行

<dependencies>
    <!-- 游戏对外服：负责和客户端保持长连接 -->
    <dependency>
        <groupId>com.iohao.game</groupId>
        <artifactId>external-core</artifactId>
        <version>21.0</version>
    </dependency>

    <!-- Broker 网关：负责路由转发 -->
    <dependency>
        <groupId>com.iohao.game</groupId>
        <artifactId>broker-server</artifactId>
        <version>21.0</version>
    </dependency>

    <!-- 逻辑服：你的业务代码跑在这里 -->
    <dependency>
        <groupId>com.iohao.game</groupId>
        <artifactId>game-server</artifactId>
        <version>21.0</version>
    </dependency>

    <!-- 网络通信实现 -->
    <dependency>
        <groupId>com.iohao.game</groupId>
        <artifactId>external-netty</artifactId>
        <version>21.0</version>
    </dependency>
</dependencies>

import com.baidu.bjf.remoting.protobuf.annotation.ProtobufClass;

// 请求：客户端发给服务器
@ProtobufClass
public class HelloRequest {
    public String name;

    @Override
    public String toString() {
        return "HelloRequest{name='" + name + "'}";
    }
}

// 响应：服务器返回给客户端
@ProtobufClass
public class HelloResponse {
    public String message;
    public long timestamp;

    @Override
    public String toString() {
        return "HelloResponse{message='" + message + "', timestamp=" + timestamp + "}";
    }
}

import com.iohao.game.action.skeleton.annotation.ActionController;
import com.iohao.game.action.skeleton.annotation.ActionMethod;

@ActionController(1)  // 主路由号 = 1
public class HelloAction {

    @ActionMethod(0)  // 子路由号 = 0
    public HelloResponse sayHello(HelloRequest request) {
        HelloResponse response = new HelloResponse();
        response.message = "Hello, " + request.name + "! 欢迎来学 ioGame。";
        response.timestamp = System.currentTimeMillis();
        return response;  // 框架自动把返回值发给客户端
    }
}

public class MyGameServer {
    public static void main(String[] args) {
        // 1. 配置对外服（客户端连进来的入口）
        ExternalServer externalServer = ExternalServer.newBuilder(8888)
            .build();

        // 2. 配置 Broker 网关（负责转发消息）
        BrokerServer brokerServer = BrokerServer.newBuilder()
            .build();

        // 3. 配置逻辑服（跑你的业务代码）
        BarSkeletonBuilder skeletonBuilder = BarSkeletonBuilder.newBuilder()
            .scanActionPackage("com.yourgame.action");  // 扫描 Action 的包路径

        GameServer gameServer = GameServer.newBuilder()
            .setBarSkeleton(skeletonBuilder.build())
            .build();

        // 4. 启动（按顺序：Broker -> 逻辑服 -> 对外服）
        brokerServer.startup();
        gameServer.startup();
        externalServer.startup();

        System.out.println("游戏服务器启动成功！端口: 8888");
    }
}

┏━━━━━ Debug. [(HelloAction.java:10).sayHello] ━━━ [cmd:1 - subCmd:0 - cmdMerge:65536]
┣ userId: 1001
┣ 参数: helloRequest : HelloRequest{name='张三'}
┣ 响应: HelloResponse{message='Hello, 张三! 欢迎来学 ioGame。'}
┣ 时间: 2 ms (业务方法总耗时)
┗━━━━━ Debug [HelloAction.java] ━━━

客户端（游戏 App / H5 / 小程序）
        ↓  WebSocket / TCP / UDP
┌─────────────────────────────┐
│      游戏对外服                │  ← 迎宾员：只负责接客（连接管理）
│  (ExternalServer)           │
└─────────────┬───────────────┘
              ↓
┌─────────────────────────────┐
│      Broker 游戏网关           │  ← 传菜员：只负责传话（路由转发）
│  (BrokerServer)             │
└─────────────┬───────────────┘
              ↓
┌─────────────────────────────┐
│      游戏逻辑服                │  ← 厨师：只负责做菜（业务逻辑）
│  (GameLogicServer)          │
└─────────────────────────────┘

@ActionController(1)
public class HelloAction {
    @ActionMethod(0)
    public HelloResponse sayHello(HelloRequest request) {
        // 这段业务代码完全不知道：
        // 1. 客户端是通过 TCP 还是 WebSocket 连接的
        // 2. 请求经过了哪些服务器节点
        // 3. 当前是在单机上运行还是在分布式集群中
        // 框架全部帮你处理了！
    }
}

跨进程通信：
对外服 → 网络协议栈 → Broker → 网络协议栈 → 逻辑服
延迟：毫秒级

同进程通信：
对外服 → 内存队列 → Broker → 内存队列 → 逻辑服
延迟：纳秒级（快 1000 倍以上）

传统方式：
┌─────────────────────────────────┐
│  class BuyItemHandler {         │
│    void handle(byte[] data) {   │
│      // 手动解析二进制数据      │
│      // 手动构造响应对象        │
│      // 手动发送响应            │
│    }                            │
│  }                              │
└─────────────────────────────────┘

ioGame 方式：
┌─────────────────────────────────┐
│  @ActionController(1)           │
│  class BuyAction {              │
│    @ActionMethod(0)             │
│    BuyResponse buy(BuyRequest)  │
│      // 只写业务逻辑            │
│      return response;           │
│    }                            │
│  }                              │
└─────────────────────────────────┘

@ActionController(1)
public class DemoAction {

    // 方式一：Protobuf 对象参数（推荐）
    @ActionMethod(0)
    public HelloResponse hello(HelloRequest request) {
        return new HelloResponse();
    }

    // 方式二：基础类型参数（简单场景）
    @ActionMethod(1)
    public void setLevel(long userId, int level) {
        // 框架自动把网络数据解析成方法参数
    }

    // 方式三：混合参数
    @ActionMethod(2)
    public boolean checkPermission(long userId, String permission) {
        return true;
    }
}

@ActionController(1)
public class ResponseAction {

    // 返回对象：自动序列化并推送给客户端
    @ActionMethod(0)
    public UserInfo getUserInfo(Long userId) {
        return new UserInfo();
    }

    // 返回 void：无需响应（fire-and-forget）
    @ActionMethod(1)
    public void heartbeat() {
        // 处理完就结束，不给客户端返回数据
    }

    // 返回基础类型：自动包装
    @ActionMethod(2)
    public int getOnlineCount() {
        return 100;
    }
}

public class MyUserHook implements UserHook {

    @Override
    public void into(long userId) {
        // 玩家上线时执行
        System.out.println("玩家 " + userId + " 上线");
        // 加载玩家数据
        // 初始化状态
        // 发送登录奖励
    }

    @Override
    public void quit(long userId) {
        // 玩家离线时执行
        System.out.println("玩家 " + userId + " 离线");
        // 保存玩家数据
        // 清理资源
    }

    @Override
    public void reconnect(long userId) {
        // 玩家断线重连时执行
        System.out.println("玩家 " + userId + " 重连");
        // 恢复游戏状态
        // 同步最新数据
    }
}

路由 = cmd（主命令） + subCmd（子命令）

例如：
@ActionController(1)   ← cmd = 1，标识一个业务模块
@ActionMethod(0)      ← subCmd = 0，标识模块内的一个具体动作

这两个数字组合成唯一的 cmdMerge：
cmdMerge = (cmd << 16) | subCmd
cmdMerge = (1 << 16) | 0 = 65536

推荐按功能模块组织路由：

├── cmd: 1 - 登录模块
│   ├── subCmd: 0 - 账号登录
│   ├── subCmd: 1 - 登出
│   └── subCmd: 2 - 获取登录状态
│
├── cmd: 2 - 玩家模块
│   ├── subCmd: 0 - 获取玩家信息
│   ├── subCmd: 1 - 更新玩家信息
│   └── subCmd: 2 - 设置头像
│
├── cmd: 3 - 背包模块
│   ├── subCmd: 0 - 获取背包列表
│   ├── subCmd: 1 - 使用道具
│   └── subCmd: 2 - 出售道具
│
└── cmd: 4 - 战斗模块
    ├── subCmd: 0 - 开始战斗
    ├── subCmd: 1 - 发送战斗指令
    └── subCmd: 2 - 结束战斗

class ActionScanner {
    public void scan(String packageName) {
        // 1. 扫描指定包下的所有类
        List<Class> classes = ClassScanner.scan(packageName);

        for (Class clazz : classes) {
            // 2. 检查是否有 @ActionController 注解
            ActionController controller = clazz.getAnnotation(ActionController.class);
            if (controller == null) continue;

            int cmd = controller.value();

            // 3. 扫描类中的方法
            for (Method method : clazz.getMethods()) {
                ActionMethod actionMethod = method.getAnnotation(ActionMethod.class);
                if (actionMethod == null) continue;

                int subCmd = actionMethod.value();

                // 4. 注册到路由表
                routeTable[cmd][subCmd] = new ActionInvoker(method, clazz);
            }
        }
    }
}

class Router {
    // 二维数组，O(1) 查找
    private ActionInvoker[][] routeTable = new ActionInvoker[65536][65536];

    public ActionInvoker findRoute(int cmd, int subCmd) {
        return routeTable[cmd][subCmd];  // 数组索引，直接定位
    }
}

业务对象 → 序列化 → 字节流 → 网络传输 → 字节流 → 反序列化 → 业务对象

// 1. 编写 .proto 文件
message UserMessage {
    required string name = 1;
    optional int32 level = 2;
    repeated string skills = 3;
}

// 2. 用 protoc 编译器生成 Java 代码
// protoc --java_out=. user.proto

// 3. 在代码中使用生成的类

// 直接用 Java 注解，不需要 .proto 文件
@ProtobufClass
public class UserMessage {
    public String name;
    public int level;
    public List<String> skills;
}

// 切换序列化协议（一行配置即可）
DataCodecKit.createDataCodec(DataCodecEnum.protobuf);
DataCodecKit.createDataCodec(DataCodecEnum.json);

// 切换传输协议（也是一行配置）
// TCP、WebSocket、UDP 之间切换

┌─────────────────────────────────────┐
│  BarMessage（统一消息对象）           │
├─────────────────────────────────────┤
│  HeadMetadata（消息头）              │
│  ├── cmd: 主命令号                   │
│  ├── subCmd: 子命令号                │
│  ├── userId: 用户标识                │
│  ├── traceId: 链路追踪 ID            │
│  └── ...                             │
├─────────────────────────────────────┤
│  Data（业务数据，Protobuf/JSON 编码） │
└─────────────────────────────────────┘

步骤 1：客户端发送请求
┌──────────┐
│  客户端   │  发送: cmd=2, subCmd=0, 数据: {userId: 1001}
└────┬─────┘
     ↓ TCP / WebSocket

步骤 2：对外服接收
┌──────────────┐
│  对外服       │  接收字节流 → 协议解码 → 提取 cmd/subCmd/userId
│  External    │  把请求转发给 Broker（不处理业务）
└──────┬───────┘
       ↓

步骤 3：Broker 路由
┌──────────────┐
│  Broker      │  查路由表: cmd=2 → 玩家逻辑服-1
│  网关        │  选择玩家逻辑服-1（负载均衡）
│              │  转发请求
└──────┬───────┘
       ↓

步骤 4：逻辑服处理
┌──────────────┐
│  逻辑服       │  查路由表: cmd=2, subCmd=0 → PlayerAction.getUserInfo
│  Logic       │  反序列化参数 → 执行业务方法 → 获取返回值
└──────┬───────┘
       ↓ 返回响应

步骤 5：反向返回
Broker ← 对外服 ← 客户端

步骤 6：客户端显示个人信息

// 同步阻塞（不好的方式）：
// 对外服收到请求后，一直等着逻辑服返回
// 这个等待期间，对外服不能处理其他请求
Response response = logicServer.handle(request);  // 阻塞！
sendToClient(response);

// 异步非阻塞（ioGame 的方式）：
// 对外服收到请求后，把请求发给 Broker，然后立刻去处理下一个请求
// 等逻辑服返回后，框架自动把响应发给客户端
broker.sendAsync(request, new Callback() {
    @Override
    public void onResponse(Response response) {
        sendToClient(response);
    }
});

// 玩家有 1000 金币
// 线程 A：玩家买道具，扣 100 金币 → 读取 1000 → 写入 900
// 线程 B：玩家领奖励，加 50 金币  → 读取 1000 → 写入 1050
// 
// 最终结果应该是 950，但可能是 900 或 1050！

public synchronized void updateGold(long userId, long delta) {
    User user = users.get(userId);
    user.gold += delta;
}

┌─────────────────────────────────────────┐
│           业务线程池（假设 4 个线程）       │
│                                         │
│  Thread-1: 处理 玩家A、玩家E、玩家I...    │
│  Thread-2: 处理 玩家B、玩家F、玩家J...    │
│  Thread-3: 处理 玩家C、玩家G、玩家K...    │
│  Thread-4: 处理 玩家D、玩家H、玩家L...    │
│                                         │
│  规则：                                   │
│  同一个玩家的所有请求 → 固定落到同一个线程  │
│  不同玩家的请求 → 分散到不同线程并行处理    │
└─────────────────────────────────────────┘

// 根据 userId 计算目标线程索引
int threadIndex = hash(userId) % threadCount;

// 示例（4 个线程）：
// 玩家 1001: hash(1001) % 4 = 1 → Thread-1
// 玩家 1002: hash(1002) % 4 = 2 → Thread-2
// 玩家 1003: hash(1003) % 4 = 3 → Thread-3
// 玩家 1004: hash(1004) % 4 = 0 → Thread-4

玩家 1001 的请求队列：
Thread-1: [请求1: 扣金币] → [请求2: 买道具] → [请求3: 查看背包]
              ↓ 串行执行，一个完了再执行下一个
           不会有并发问题！

房间 101 里有 4 个玩家：
玩家 A (userId=1001) → Thread-1
玩家 B (userId=1002) → Thread-3
玩家 C (userId=1003) → Thread-2
玩家 D (userId=1004) → Thread-1

问题：玩家 A 和 D 都落在 Thread-1，但 B 和 C 落在别的线程
房间对象会被多个线程同时修改，仍然需要加锁

// 自定义线程绑定规则
public class MyThreadBinder implements RequestMessageClientProcessorHook {

    @Override
    public int selectThreadIndex(RequestMessage request) {
        // 如果请求带了 roomId，按 roomId 选择线程
        if (request.hasRoomId()) {
            return hash(request.getRoomId()) % threadCount;
        }
        // 否则按 userId 选择线程
        return hash(request.getUserId()) % threadCount;
    }
}

@ActionController(1)
public class BadExample {
    @ActionMethod(0)
    public void badPractice(long userId) {
        // 错误：直接查数据库会阻塞整个业务线程
        // 这个线程上还有其他玩家的请求在排队！
        User user = userDao.load(userId);  // 阻塞！危险！
        user.gold += 100;
    }
}

@ActionController(1)
public class GoodExample {
    @ActionMethod(0)
    @VirtualThread  // 使用虚拟线程执行这个方法
    public void goodPractice(long userId) {
        // 虚拟线程处理阻塞任务
        User user = userDao.load(userId);  // 阻塞的是虚拟线程，不影响平台线程
        user.gold += 100;
    }
}

// 启动时注册
Map<String, Handler> routeMap = new HashMap<>();
routeMap.put("1-0", new HelloHandler());
routeMap.put("1-1", new LoginHandler());

// 运行时查找
Handler handler = routeMap.get("1-0");
// 过程：计算 hashCode → 定位数组位置 → 处理冲突（链表/红黑树）
// 时间复杂度：O(1) 平均，但有 hash 计算和冲突处理的开销

// 启动时注册
ActionInvoker[][] routeTable = new ActionInvoker[65536][65536];
routeTable[1][0] = new ActionInvoker(HelloAction.class, "sayHello");
routeTable[1][1] = new ActionInvoker(LoginAction.class, "doLogin");

// 运行时查找
ActionInvoker invoker = routeTable[cmd][subCmd];
// 过程：计算数组偏移地址 → 直接读取
// 时间复杂度：O(1)，且是最快的 O(1)（比 HashMap 快得多）

// 反射调用（慢）
Method method = clazz.getMethod("sayHello", HelloRequest.class);
method.invoke(instance, request);  // 反射有性能开销

// 启动期：扫描注解，缓存 MethodHandle
MethodHandle handle = lookup.unreflect(method);

// 运行期：直接调用（接近原生方法调用性能）
handle.invoke(instance, request);

1. 开发者编写 .proto 文件（定义消息结构）
2. 用 protoc 编译器生成 Java 代码
3. 把生成的代码加入项目
4. 运行时调用生成的代码进行序列化/反序列化

1. 开发者用 Java 注解定义消息结构
2. 编译期/启动期：框架扫描注解，生成等效的 Protobuf 序列化代码
3. 运行时：直接调用生成的代码

传统路径（多次拷贝）：
网络缓冲区 → byte[]（拷贝1）→ Protobuf 解析 → Java 对象
Java 对象 → Protobuf 编码 → byte[]（拷贝2）→ 网络缓冲区

ioGame 优化路径（零拷贝）：
网络缓冲区（Direct ByteBuf）→ Protobuf 直读 → Java 对象
Java 对象 → Protobuf 直写 → Direct ByteBuf → 网络发送

// 抽象接口
interface DataCodec {
    byte[] encode(Object obj);
    <T> T decode(byte[] data, Class<T> clazz);
}

// Protobuf 实现
class ProtobufDataCodec implements DataCodec { ... }

// JSON 实现
class JsonDataCodec implements DataCodec { ... }

// 运行时切换
DataCodecKit.createDataCodec(DataCodecEnum.protobuf);

场景 1：玩家买道具
背包逻辑服 → 调用玩家逻辑服（扣金币）→ 调用邮件逻辑服（发奖励）

场景 2：战斗结算
战斗逻辑服 → 调用排行榜逻辑服（更新排名）→ 调用成就逻辑服（检查成就）

@ActionController(3)
public class BagAction {

    @ActionMethod(0)
    public BuyResult buyItem(BuyRequest request, FlowContext flowContext) {
        // 1. 调用玩家逻辑服扣金币
        DeductGoldRequest deductReq = new DeductGoldRequest();
        deductReq.userId = request.userId;
        deductReq.amount = request.price;

        DeductGoldResponse deductResp = flowContext.invokeModuleMessage(
            deductReq,  // 请求对象
            2,          // 目标逻辑服的 cmd（玩家模块）
            1           // 目标方法的 subCmd（扣金币）
        );

        if (!deductResp.success) {
            throw new MsgException("金币不足");
        }

        // 2. 添加道具到背包
        addItem(request.userId, request.itemId);

        // 3. 发布事件（异步通知其他系统）
        EventBusKit.fire(new ItemBoughtEvent(request.userId, request.itemId));

        return new BuyResult(true, "购买成功");
    }
}

你的代码：
flowContext.invokeModuleMessage(req, 2, 1);

框架底层自动处理：
┌─────────────────────────────────────────┐
│  同进程？→ 直接内存引用传递（最快）         │
│  同机器不同进程？→ 本地回环网络通信         │
│  不同机器？→ TCP 长连接通信                │
└─────────────────────────────────────────┘

// 定义事件
public class PlayerLevelUpEvent {
    public long userId;
    public int oldLevel;
    public int newLevel;
}

// 发布事件（在主业务逻辑中）
EventBusKit.fire(new PlayerLevelUpEvent(userId, 10, 11));

// 处理事件（在其他地方订阅）
public class LevelUpHandler implements EventHandler<PlayerLevelUpEvent> {
    @Override
    public void handle(PlayerLevelUpEvent event) {
        // 检查是否有新成就解锁
        checkAchievements(event.userId, event.newLevel);
        // 通知好友
        notifyFriends(event.userId, "我升级了！");
        // 更新排行榜
        updateRank(event.userId);
    }
}

// 登录请求
@ProtobufClass
public class LoginRequest {
    public String account;
    public String password;
}

// 登录响应
@ProtobufClass
public class LoginResponse {
    public boolean success;
    public String token;
    public long userId;
    public String errorMsg;
}

@ActionController(1)  // 登录模块
public class LoginAction {

    @ActionMethod(0)  // 登录
    public LoginResponse login(LoginRequest request, FlowContext flowContext) {
        LoginResponse response = new LoginResponse();

        // 1. 验证账号密码（实际项目中查数据库或调用认证服务）
        User user = userDao.findByAccount(request.account);
        if (user == null || !user.password.equals(request.password)) {
            response.success = false;
            response.errorMsg = "账号或密码错误";
            return response;
        }

        // 2. 绑定 userId 到当前连接
        // 这步很重要：绑定后框架才知道这条连接对应哪个玩家
        flowContext.setUserId(user.id);

        // 3. 生成 Token（可选，用于后续请求验证）
        String token = generateToken(user.id);

        response.success = true;
        response.token = token;
        response.userId = user.id;

        return response;
    }

    @ActionMethod(1)  // 登出
    public void logout(FlowContext flowContext) {
        long userId = flowContext.getUserId();
        // 保存玩家数据
        saveUserData(userId);
        // 清除绑定
        flowContext.setUserId(0);
    }
}

public class JwtVerifyHandler implements VerifyHandler {
    @Override
    public boolean verify(VerifyRequest request) {
        // 验证 JWT Token
        return JwtUtil.verify(request.token);
    }
}

@ProtobufClass
public class CreateRoomRequest {
    public int gameType;      // 游戏类型：1=斗地主, 2=麻将...
    public int maxPlayers;    // 最大人数
}

@ProtobufClass
public class RoomInfo {
    public long roomId;
    public int gameType;
    public List<Long> playerIds;
    public int status;        // 0=等待中, 1=游戏中
}

@ProtobufClass
public class JoinRoomRequest {
    public long roomId;
}

@ProtobufClass
public class GameActionRequest {
    public long roomId;
    public int actionType;
    public String data;
}

@ActionController(10)  // 房间模块
public class RoomAction {

    @ActionMethod(0)  // 创建房间
    public RoomInfo createRoom(CreateRoomRequest request, FlowContext flowContext) {
        long userId = flowContext.getUserId();

        // 生成房间 ID
        long roomId = RoomIdGenerator.nextId();

        // 创建房间对象
        Room room = new Room(roomId, request.gameType, request.maxPlayers);
        room.addPlayer(userId);

        // 缓存房间
        RoomCache.put(roomId, room);

        // 记录玩家当前所在房间
        PlayerRoomCache.put(userId, roomId);

        return room.toInfo();
    }

    @ActionMethod(1)  // 加入房间
    public RoomInfo joinRoom(JoinRoomRequest request, FlowContext flowContext) {
        long userId = flowContext.getUserId();
        Room room = RoomCache.get(request.roomId);

        if (room == null) {
            throw new MsgException(-1001, "房间不存在");
        }
        if (room.isFull()) {
            throw new MsgException(-1002, "房间已满");
        }
        if (room.isPlaying()) {
            throw new MsgException(-1003, "游戏已开始");
        }

        room.addPlayer(userId);
        PlayerRoomCache.put(userId, request.roomId);

        // 广播给房间内所有玩家：有人加入了
        broadcastToRoom(request.roomId, new PlayerJoinNotification(userId));

        return room.toInfo();
    }

    @ActionMethod(2)  // 开始游戏
    public void startGame(StartGameRequest request, FlowContext flowContext) {
        long userId = flowContext.getUserId();
        Room room = RoomCache.get(request.roomId);

        if (room == null) {
            throw new MsgException("房间不存在");
        }
        if (room.getOwnerId() != userId) {
            throw new MsgException("只有房主可以开始游戏");
        }

        room.startGame();

        // 广播游戏开始
        broadcastToRoom(request.roomId, new GameStartNotification());
    }

    @ActionMethod(3)  // 发送游戏动作
    public void sendAction(GameActionRequest request, FlowContext flowContext) {
        long userId = flowContext.getUserId();
        Room room = RoomCache.get(request.roomId);

        if (room == null || !room.isPlaying()) {
            return;
        }

        // 处理游戏动作
        room.processAction(userId, request);

        // 广播游戏状态更新
        broadcastToRoom(request.roomId, room.getGameState());
    }
}

private void broadcastToRoom(long roomId, Object message) {
    Room room = RoomCache.get(roomId);
    if (room == null) return;

    for (Long playerId : room.getPlayerIds()) {
        UserSession session = UserSessions.getUserSession(playerId);
        if (session != null) {
            session.writeAndFlush(message);
        }
    }
}

// 单播：给特定玩家发消息
UserSession session = UserSessions.getUserSession(userId);
session.writeAndFlush(message);

// 广播：给所有在线玩家发消息
UserSessions.broadcast(message);

// 多播：给满足条件的玩家发消息
List<Long> targetUserIds = ...;
for (Long id : targetUserIds) {
    UserSession session = UserSessions.getUserSession(id);
    if (session != null) {
        session.writeAndFlush(message);
    }
}

// 在 Action 方法中，通过 FlowContext 获取当前玩家的会话
@ActionMethod(0)
public void someAction(FlowContext flowContext) {
    // 给当前玩家推送消息
    flowContext.writeAndFlush(new Notification("你获得了一个宝箱！"));
}

@ActionController(11)  // 战斗模块
public class BattleAction {

    @ActionMethod(2)  // 战斗结算
    public BattleResult settleBattle(BattleSettleRequest request, FlowContext flowContext) {
        // ... 计算战斗结果 ...

        // 更新排行榜（调用排行榜逻辑服）
        UpdateRankRequest rankReq = new UpdateRankRequest();
        rankReq.userId = request.userId;
        rankReq.score = battleResult.score;

        flowContext.invokeModuleMessage(rankReq, 20, 0);

        // 检查成就（调用成就逻辑服）
        CheckAchievementRequest achReq = new CheckAchievementRequest();
        achReq.userId = request.userId;
        achReq.achievementType = "first_win";

        flowContext.invokeModuleMessage(achReq, 21, 0);

        return battleResult;
    }
}

// 匹配逻辑服
@ActionController(12)
public class MatchAction {

    @ActionMethod(0)
    public MatchResult match(MatchRequest request, FlowContext flowContext) {
        // 找一个压力最小的房间服
        int targetLogicServerId = selectLeastLoadedRoomServer();

        // 把玩家绑定到这个房间服
        flowContext.getBarMessage().setBindingLogicServerId(targetLogicServerId);

        return new MatchResult(targetLogicServerId);
    }
}

磁盘/网络 → 内核缓冲区 → JVM 堆内存 → 业务对象
（每次拷贝都消耗 CPU 和内存带宽）

网络 → Direct ByteBuf（堆外内存）→ 业务对象
（减少了堆内外拷贝）

逐条处理：
收到消息1 → 解码 → 处理 → 响应
收到消息2 → 解码 → 处理 → 响应
... （大量上下文切换）

批量处理：
收到 [消息1, 消息2, 消息3, ...] → 批量解码 → 批量处理 → 批量响应
... （减少上下文切换，摊薄固定开销）

GC 问题：频繁创建对象 → GC 频繁 → 停顿 → 延迟抖动

ioGame 的优化策略：
1. 预分配：启动时分配固定内存（Disruptor Ring Buffer）
2. 对象复用：运行时循环使用对象，不创建新对象
3. 零反射：启动期解析，运行期直接调用
4. 堆外内存：Direct Buffer 减少堆内存压力

目标：将 GC 频率从每秒数次降至数分钟一次

┌──────────────────────────────┐
│          一个 JVM 进程          │
│                              │
│  ┌────────┐  ┌─────┐  ┌───┐ │
│  │ 对外服  │  │Broker│  │逻辑服│ │
│  └────────┘  └─────┘  └───┘ │
└──────────────────────────────┘

特点：
- 三者在一个进程内，通过内存直接通信
- 零网络延迟，调试方便
- 适合：开发调试、快速原型、小规模部署

┌──────────┐        ┌──────────────────┐
│  对外服   │        │   JVM 进程        │
│  独立进程 │        │                  │
└────┬─────┘        │  ┌─────┐  ┌───┐  │
     ↓ 网络通信      │  │Broker│  │逻辑服│  │
  （TCP长连接）      │  └─────┘  └───┘  │
                    └──────────────────┘

特点：
- 对外服独立部署，内部 Broker+逻辑服同进程
- 外部流量隔离，内部零拷贝
- 适合：中小型生产环境

┌──────┐    ┌──────┐    ┌──────┐
│对外服1│    │对外服2│    │对外服3│  ← 可独立扩容
└──┬───┘    └──┬───┘    └──┬───┘
   ↓           ↓           ↓
┌──────────────────────────────────┐
│        Broker 集群                │  ← 自带负载均衡
│  ┌─────┐  ┌─────┐  ┌─────┐      │
│  │B-1  │  │B-2  │  │B-3  │      │
│  └─────┘  └─────┘  └─────┘      │
└────────────┬─────────────────────┘
             ↓
┌──────────────────────────────────┐
│       逻辑服集群                  │  ← 可独立扩容
│  ┌─────┐  ┌─────┐  ┌─────┐      │
│  │登录服│  │战斗服│  │排行服│      │
│  └─────┘  └─────┘  └─────┘      │
└──────────────────────────────────┘

特点：
- 完全水平扩展，故障隔离
- 适合：大型生产环境、高可用要求

// 开发模式：三者同进程
public static void main(String[] args) {
    // 简单的启动方式
    IoGameSimpleHelper.run();
}

// 生产模式：分别部署
// 对外服部署在一台机器
// Broker 部署在多台机器
// 逻辑服按模块独立部署

public class MyUserHook implements UserHook {

    @Override
    public void reconnect(long userId) {
        // 恢复玩家状态
        Player player = PlayerCache.get(userId);
        if (player != null) {
            // 同步最新游戏状态给客户端
            UserSession session = UserSessions.getUserSession(userId);
            session.writeAndFlush(new SyncGameState(player));
        }
    }
}

@ActionController(1)
public class PlayerAction {

    @ActionMethod(0)
    @VirtualThread  // 使用虚拟线程处理阻塞 I/O
    public PlayerInfo loadPlayer(Long userId) {
        // 慢查询在虚拟线程中执行，不阻塞业务线程
        Player player = playerDao.load(userId);
        return convertToInfo(player);
    }
}

-Xms2g -Xmx2g          # 固定堆内存，避免动态扩缩
-XX:+UseZGC            # 使用 ZGC 低延迟垃圾回收器
-XX:+UseStringDeduplication  # 字符串去重

net.core.rmem_max = 16777216   # 接收缓冲区最大值
net.core.wmem_max = 16777216   # 发送缓冲区最大值

第一阶段：入门（1-2 周）
├── 理解游戏服务器 vs Web 服务器的区别
├── 理解 ioGame 三层架构
├── 成功运行 Hello World
├── 编写第一个 Action（登录/查询）
└── 掌握路由系统的使用

第二阶段：进阶（2-4 周）
├── 理解线程模型（为什么不需要加锁）
├── 掌握会话管理（UserSession）
├── 学会广播和推送
├── 实践跨逻辑服调用
└── 完成一个完整的小项目（如简单棋牌）

第三阶段：高级（持续）
├── 深入理解 Disruptor 原理
├── 性能调优和压测
├── 分布式部署实践
├── 自定义扩展（协议、插件）
└── 阅读框架源码