魔数须为4字节固定int型（如0x12345678）以区分非法连接，版本字段占1字节便于平滑升级；长度字段紧随其后且定长4字节，表示消息体字节数并校验上限；消息体首选protobuf，避免嵌套过深，不加应用层分隔符。
魔数和版本字段怎么设才不踩兼容性坑
魔数不是随便凑的4个字节，它得能一眼区分非法连接和协议错位。比如服务端用 0x12345678，但客户端误连了 HTTP 服务，收到的是 HTTP/1.1 响应头——这时候解码器必须立刻丢弃并关闭连接，而不是继续读后续字段导致越界或崩溃。
- 魔数建议固定为 4 字节整型（
int），避免大小端混淆；别用字符串如"MAGIC"，解析时要额外判断字节长度和编码 - 版本号字段推荐占 1 字节（
byte），够覆盖 0–255 版本，且升级时老服务端可拒绝未知版本（比如收到version=5但只支持 0–3），而非硬解析失败 - 千万别把版本号和魔数合并成一个字段——升级魔数等于全量断连，而保留魔数、仅升版本才是平滑演进
消息长度字段放哪？为什么必须放头部最前面
长度字段必须紧随魔数和版本之后、且是定长（推荐 4 字节 int），否则无法解决 TCP 粘包/半包问题。Netty 的 ByteToMessageDecoder 靠它判断“这次要不要等更多数据”。
- 如果长度字段放在消息体里（比如 JSON 中的
"length":123），那得先完整读完整个包再解析——这等于放弃流式处理，内存暴涨且无法及时识别恶意超长包 - 长度值应表示「消息体字节数」，不含头部；否则解码器计算偏移容易出错，尤其当头部含可变字段时（比如带扩展标志位）
- 务必校验长度上限，例如
if (length > 1024 * 1024) { ctx.close(); return; }，防内存耗尽攻击
消息体用 Protobuf 还是 JSON？二进制结构怎么对齐性能与调试
Protobuf 是生产首选，但别一上来就写 .proto 文件堆功能——先定义最小可用集：一个 SocketHeader + 一个 bytes body 即可，业务消息由上层根据 cmd 字段分发。
- JSON 适合开发期快速验证，但序列化后体积大、解析慢，且无法跨语言强约束；上线前必须切到 Protobuf
- Protobuf 消息体不要嵌套太深，
repeated字段在 Netty 解码时可能触发多次内存拷贝；单次消息建议控制在 10 层以内 - 消息体前不加任何分隔符或校验和——那是链路层该干的事；应用层校验（如 CRC32）只在安全要求极高场景加，多数 IM/游戏服务靠 TLS 或业务 ACK 保证
解码器里 resetReaderIndex() 调用时机不对会直接卡死连接
这是最常被抄错的一行。当 in.readableBytes() 时，你得立刻 <code>return；但一旦开始读头部，发现 bodyLength 超限或 in.readableBytes() ，就必须调 <code>in.resetReaderIndex()，否则下一次 decode() 会从错误位置开始读，最终协议错乱。
- 错误写法：
if (in.readableBytes() —— 缺少 <code>resetReaderIndex()，下次读到的全是脏数据 - 正确顺序：读完魔数/版本/指令/长度 → 检查长度是否合法 → 检查 body 是否可读完 → 不足则
resetReaderIndex()并return - 别在解码器里做耗时操作（如 DB 查询、远程调用），它跑在 IO 线程；业务逻辑必须抛给
ctx.executor().execute()或ChannelHandler后续处理器
协议设计最麻烦的从来不是字段怎么排，而是所有环节都得对齐“谁负责检查、谁负责恢复、谁负责拒绝”。一个没校验的魔数，或一处漏掉的 resetReaderIndex()，都会让服务在高并发下静默失联。
