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