Netty 粘包拆包处理

概述

TCP 是流式协议，字节像水流一样没有边界。客户端连续发送多条游戏消息时，服务器可能一次读到多条（粘包），也可能读到一条的一半（拆包）。游戏服务器通信的第一步就是解决"一条完整消息的边界在哪"——这就是拆包/粘包处理。本文讲清问题根源、Netty 三种内置解码器、以及自定义解码器的正确写法。

---

一、为什么会有粘包拆包

1.1 现象

客户端发送三条消息：A、B、C
服务器可能读到的几种情况：
  正常：A | B | C
  粘包：ABC（三条一起到）
  AB | C（前两条粘在一起）
  拆包：A | BC 的前半部分 ...

1.2 根本原因

TCP 是一个字节流通道：
  1. 发送方可能把多个小包合并发送（Nagle 算法）
  2. 接收方 read 缓冲区大小不定，一次可能读多/读少
  3. 网络传输本身没有"消息边界"概念
  只有应用层协议定义边界，接收端才能正确切分

因素	说明
Nagle 算法	小包延迟合并发送，引发粘包
内核缓冲区	读写缓冲区合并/拆分字节
read 调用时机	一次 read 拿到多个/半个消息

1.3 三种解决方案

方案	原理	典型解码器
定长消息	每条消息固定长度，不足补齐	FixedLengthFrameDecoder
分隔符	消息间用特殊字符分隔	LineBasedFrameDecoder、DelimiterBasedFrameDecoder
长度字段	消息头携带长度，按长度切分	LengthFieldBasedFrameDecoder

游戏服务器选择：
  定长 → 浪费带宽，消息大小不均
  分隔符 → 消息体可能包含分隔符字符
  长度字段 → 灵活、精确，游戏协议的主流方案

---

二、三种内置解码器对比

2.1 LineBasedFrameDecoder（行分隔）

按换行符 \n 或 \r\n 切分，多用于文本协议（HTTP 行、命令行）。

优点：实现简单
缺点：消息体不能包含换行符；性能一般
游戏场景：基本不用（游戏协议是二进制）

2.2 DelimiterBasedFrameDecoder（自定义分隔符）

允许自定义一个或多个分隔符，按分隔符切分。

构造：
  new DelimiterBasedFrameDecoder(maxFrameLength, Delimiter... delimiters)

优点：灵活，可用于简单自定义文本协议
缺点：
  需要约定消息中不出现分隔符
  需要转义或长度校验，安全性要自己处理
  游戏场景：二进制协议不用

2.3 LengthFieldBasedFrameDecoder（长度字段）

消息头携带长度字段，解码器先读长度，再按长度取完整消息。游戏协议的标准方案。

构造参数（重点）：
  maxFrameLength       单条消息最大长度
  lengthFieldOffset    长度字段在消息头中的偏移
  lengthFieldLength    长度字段占用的字节数
  lengthAdjustment     长度字段值 + 该调整值 = 实际负载长度
  initialBytesToStrip  切出完整帧后剥离的头部字节数

2.4 三者对比

解码器	边界依据	适用协议	游戏适用度
FixedLengthFrameDecoder	固定长度	定长协议	低
LineBasedFrameDecoder	换行符	文本协议	低
DelimiterBasedFrameDecoder	自定义分隔符	文本协议	低
LengthFieldBasedFrameDecoder	长度字段	二进制协议	高

---

三、LengthFieldBasedFrameDecoder 深入

3.1 四种典型配置

长度字段（Length）为 2 字节时，lengthFieldLength = 2。

场景一：长度字段紧跟在头部最前，长度值只包含消息体

协议：| Length(2) | Body(N) |
配置：
  lengthFieldOffset = 0
  lengthFieldLength = 2
  lengthAdjustment = 0
  initialBytesToStrip = 2
效果：切出完整帧后去掉 Length 头，剩余纯 Body

场景二：长度字段在前，长度值包含 Length 自身

协议：| Length(2) | Body(N) |，Length = 2 + N
配置：
  lengthFieldOffset = 0
  lengthFieldLength = 2
  lengthAdjustment = -2
  initialBytesToStrip = 2

场景三：完整消息头在前（含固定头 + 长度字段 + 消息体）

协议：| Magic(1) | Version(1) | Length(2) | Body(N) |
配置：
  lengthFieldOffset = 2（跳过 Magic + Version）
  lengthFieldLength = 2
  lengthAdjustment = 0（Length 只含 Body）
  initialBytesToStrip = 0（保留完整消息头给后续解码器）

场景四：长度字段值包含整个消息（头部 + 消息体）

协议：| Magic(1) | Length(2) | Body(N) |，Length = 3 + N
配置：
  lengthFieldOffset = 1
  lengthFieldLength = 2
  lengthAdjustment = -3
  initialBytesToStrip = 0

3.2 参数计算口诀

lengthAdjustment = 实际载荷起点距长度字段末尾的距离
实际载荷 = 长度字段之后的部分 + lengthAdjustment

关键判断：
  Length 只含 Body → lengthAdjustment = 0
  Length 含 Length 自己 → lengthAdjustment = -lengthFieldLength
  Length 含整个帧 → lengthAdjustment = -(头部总长)

3.3 半包与超限处理

半包：Length 读到 1000 字节，但当前只到了 400 字节
  解码器自动缓存剩余字节，等数据到齐再产出完整帧
  （这正是框架的价值，无需自己维护残缺缓冲）

超限：Length 超过 maxFrameLength
  抛出 TooLongFrameException
  建议在 pipeline 里放异常处理器统一断连/告警

---

四、自定义解码器

4.1 何时需要自定义解码器

LengthFieldBasedFrameDecoder 只负责"切出完整帧"
切出的仍是一段字节（ByteBuf）
要得到业务可用的"消息对象"，还需要解码器：
  把字节流 → 按协议解析出字段 → 组装成消息对象

4.2 继承 ByteToMessageDecoder

ByteToMessageDecoder 是拆包解码器的父类，内部维护 cumulation 累积缓冲，自动处理半包。

public class GameMessageDecoder extends ByteToMessageDecoder {

    @Override
    protected void decode(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) {
        // 半包：字节不足，直接返回，框架等待更多数据
        if (in.readableBytes() < HEADER_LENGTH) {
            return;
        }
        // 记录当前读指针，用于半包时回退
        in.markReaderIndex();
        short opcode = in.readShort();
        int length = in.readInt();
        // 长度非法直接关闭连接
        if (length < 0 || length > MAX_BODY_LENGTH) {
            ctx.close();
            return;
        }
        // 消息体未到齐：回退读指针，等待后续数据
        if (in.readableBytes() < length) {
            in.resetReaderIndex();
            return;
        }
        byte[] body = new byte[length];
        in.readBytes(body);
        out.add(new GameMessage(opcode, body));
    }
}

要点总结：
  数据不足 → return（不要消费任何字节）
  读不完 → 用 markReaderIndex / resetReaderIndex 回退
  每次 decode 可能产出 0 个或多个对象
  解码过程中不要做耗时逻辑（解码在 IO 线程）

4.3 编码器：继承 MessageToByteEncoder

编码是把消息对象写回字节流，方向相反，天然不会有半包问题。

public class GameMessageEncoder extends MessageToByteEncoder<GameMessage> {

    @Override
    protected void encode(ChannelHandlerContext ctx, GameMessage msg, ByteBuf out) {
        out.writeShort(msg.getOpcode());
        byte[] body = msg.getBody();
        out.writeInt(body.length);
        out.writeBytes(body);
    }
}

编码器注意：
  一个消息对象 → 恰好一个完整帧
  不要在 encode 里做耗时操作（同样在 IO 线程）
  若使用内存池分配，出站消息 Netty 会自动释放

4.4 组合使用

Pipeline 装配顺序（入站从左到右）：
  LengthFieldBasedFrameDecoder   → 按长度切出完整帧
  GameMessageDecoder             → 帧 → GameMessage 对象
  GameMessageHandler             → 业务处理

出站方向（反向）：
  GameMessageEncoder             → GameMessage 对象 → 完整帧字节

为什么拆两层：
  切帧与协议解析职责分离
  若协议升级（如换长度字段格式），只改切帧层
  若消息字段调整，只改解析层

---

五、性能与安全要点

5.1 限制单条消息大小

maxFrameLength 必须设置：
  防止恶意客户端声明超大长度，导致内存耗尽
  游戏建议值：4KB - 16KB（视最大消息而定）
  超过上限 → 断连 + 告警（防攻击）

5.2 校验长度合法性

Length 不是简单信任：
  负数 / 超上限 → 立即断开
  配合 maxFrameLength 双保险
  这是反外挂的第一道防线（协议层）

5.3 解码器线程模型

解码在哪个线程执行：
  默认在 Channel 绑定的 EventLoop（IO 线程）
  解码尽量轻量：只做字节拷贝与字段解析
  序列化（如 Protobuf）也在解码器里做，注意开销
  耗时解析应评估是否转移到业务线程池

---

六、常见问题排查

现象	可能原因	排查思路
消息偶发解析错乱	长度字段偏移算错	打印十六进制核对协议布局
全部消息拼在一起	忘配 LengthFieldBasedFrameDecoder	检查 Pipeline
大消息频繁截断	maxFrameLength 过小	加大并观察
解析后消息体为空	initialBytesToStrip 配置错误	核对剥离字节数
高并发下内存上涨	累积缓冲未释放/长度异常	检查超限处理与解码器释放

排查利器：
  日志打印收到/发出的十六进制报文
  用 Wireshark 抓包对比协议字节
  压测时监控 GC 与内存（排查 ByteBuf 泄漏）

---

七、小结

粘包拆包是游戏 TCP 通信的第一个技术关口。根因是 TCP 无消息边界，解法是应用层定义边界：定长、分隔符、长度字段三选一，游戏协议几乎都选长度字段方案。LengthFieldBasedFrameDecoder 负责按长度切出完整帧，四个参数（Offset/Length/Adjustment/Strip）要按协议布局精确计算；再配合继承 ByteToMessageDecoder 的自定义解码器，用"读指针回退 + 累积缓冲"处理半包，把字节解析成消息对象。切帧与解析分两层，职责清晰且便于演进。