面向特定协议的解析工具包必须按协议字段粒度建模、严格隔离编解码逻辑、禁止跨协议复用结构体；字段名首字母大写、类型精确匹配、顺序一字不差、用unsafe.sizeof校验大小、变长字段拆分为长度+内容两步读取、tcp粘包需协议层解决、目录按协议而非功能划分、测试用真实抓包数据验证。
直接说结论：面向特定协议的解析工具包，必须按协议字段粒度建模、严格隔离编解码逻辑、禁止跨协议复用结构体——不是写得越通用越好，而是越贴近协议越稳。
协议字段必须一对一映射到导出字段
binary.Read 不会报错跳过小写字段，它直接静默忽略。比如协议文档写“Version: uint16”，你写 version uint16，读出来永远是 0；必须写成 Version uint16。同样，协议里“Reserved: 3 bytes”，不能塞进一个 Reserved [3]byte 就完事——要确认这 3 字节是否参与校验、是否需填充对齐，否则 unsafe.Sizeof 算出来的 struct 大小和协议标称长度不一致，后续字段全偏移。
- 所有字段名首字母大写，哪怕协议里叫
msg_type，Go 里也得是MsgType uint8 - 禁用
int/uint，协议写length: uint32，就只用Length uint32 - 用
unsafe.Sizeof(Header{})校验 struct 实际字节数，必须和协议文档完全相等 - 协议字段顺序一字不差，调换
Checksum和Timestamp位置，整个包就废了
变长字段必须拆成“长度+内容”两步读
binary.Read 遇到 string 或 []byte 必 panic，这不是 bug，是设计契约。协议里“用户名”不能裸定义为 Name string，而要拆成 NameLen uint16 + NameBuf [256]byte，或更安全地：先读长度，再动态分配。
- 先
binary.Read(r, order, &nameLen)，类型必须是uint16或uint32 - 立刻校验：
if nameLen > 128 { return errors.New("name too long") } - 再
io.ReadFull(r, nameBuf[:nameLen])，别用Read，防止粘包截断 - 最后转字符串：
string(bytes.TrimRight(nameBuf[:nameLen], "\x00"))
TCP 粘包必须在协议层解决，不能甩锅给 binary.Read
把 net.Conn 直接传给 binary.Read，等于让解析器在字节流里盲猜边界。一次 Read() 可能只拿到半个包长字段，下一次又拼了两条消息——魔数错位、长度字段被截半，后面全乱。
- 协议头最前 N 字节必须是包总长（如
uint32），且该字段自身字节序要和协议文档一致 - 先
binary.Read(r, order, &pkgLen)提取完整长度，order 错会导致pkgLen是 16777216 这种值，直接 OOM - 立刻校验：
if pkgLen == 0 || pkgLen > 1024*1024 - 再
io.ReadFull(r, data[:pkgLen])拿到完整包，之后才用bytes.NewReader(data)交给binary.Read
工具包目录结构要体现协议边界，而非功能类型
别建一个叫 codec 的包，然后往里塞 HTTP、MQTT、自定义二进制协议的代码。每个协议解析逻辑应独占一个包，名字就是协议名缩写，比如 protox 或 myrpc，内部只放这个协议的 Header、Packet、Decode、Encode。
- 公开 API 只暴露
Decode(io.Reader) (*Packet, error)和Encode(*Packet, io.Writer) error - 所有内部结构体、常量、字节序选择都封在包内，不对外泄露
binary.LittleEndian这类细节 - 测试文件
protox_test.go必须用真实抓包 hex 数据做基准验证，不能只测 struct 序列化 - 如果协议有多个版本（v1/v2），用子包
protox/v2，而不是在同一个 struct 里加CompatMode bool
最容易被忽略的是：协议变更时，90% 的问题不出现在业务逻辑，而出现在 struct 字段顺序微调、长度字段字节序切换、或新增保留字段未填零——这些都得靠 unsafe.Sizeof + 抓包 hex 对照 + 边界长度校验三者闭环验证，缺一不可。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
