自定义协议握手必须严格按“先协商版本、再交换能力、最后确认可通信”三步执行；版本字段需置于协议头最前并用uint16定长编码，能力字段推荐位图或长度前缀+字节流，全程需魔数校验、总长校验及独立状态机隔离。
Go 语言做自定义协议握手，核心不是“发个 hello”，而是「先协商版本，再交换能力，最后确认可通信」——漏掉任一环节，后续所有消息都可能被静默丢弃或解析 panic。
为什么 handshake 必须带版本字段
不带版本号的握手等同于裸奔：客户端用 v2 协议发包，服务端只认 v1，结果 readPacket 解出长度头后直接读错字节数，io.ReadFull 阻塞或返回 io.ErrUnexpectedEOF；更糟的是，双方都以为连上了，只是后续数据全乱码。
- 版本字段必须放在协议头最前面（比如 header 前 2 字节），且用定长类型（
uint16），不能是字符串或变长编码 - 服务端收到后必须立即校验：若
version >= 0x0200但自己只支持到0x0101，应立刻关闭连接，不要尝试兼容 - 别在版本号里塞语义（如
0x0102表示 “v1.2”），就用纯递增整数（0x0001,0x0002），避免解析歧义
能力交换字段怎么设计才不翻车
能力（capability）不是功能列表，而是「能否安全处理某类 payload」的布尔断言。常见错误是把 ["gzip", "protobuf", "tls13"] 直接 JSON 序列化塞进握手包 —— 既没长度前缀，又没对齐字节序，binary.Read 一读就 panic。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 能力字段建议用位图（bitmask）：每个 bit 代表一项能力（如 bit0 = 支持 msgpack，bit1 = 支持加密 header），固定 4 字节
uint32 - 若能力项过多，改用「长度前缀 + byte slice」：先写
uint16表示能力字节数，再写对应字节流，接收方严格用io.ReadFull读满 - 关键能力必须双向确认：比如客户端声明支持
extensionEncryptedClientHello，服务端响应时也要在能力字段中置对应 bit，否则客户端不应启用该功能
如何避免 handshake 后消息解析失败
握手成功 ≠ 协议栈就绪。很多线上故障源于 handshake 返回后，业务层直接调用 readPacket，却没重置状态机 —— 比如上一个连接残留的未读完字节还在 buffer 里，新连接一上来就读到脏数据。
立即学习“go语言免费学习笔记（深入）”；
- 每次
conn.Accept()后，必须新建独立的bufio.Reader或封装好的Conn实例，不能复用旧连接的 reader - handshake 包本身要参与长度校验：整个握手包（含 version + capability + 魔数 + 校验和）必须有明确总长字段，且服务端用
io.ReadFull一次性读完，不能分多次Read - 魔数（magic number）不能省：header 开头放固定 4 字节（如
[0x47, 0x4f, 0x50, 0x52]对应 "GOPR"），服务端先校验，不匹配直接断连，避免误解析后续流量
真正难的不是写出握手逻辑，而是让两端对「什么算握手成功」有一致的原子判断 —— 版本、能力、魔数、校验和，四个条件缺一不可，且必须在同一个 TCP 包内完成验证。任何一项靠“后续消息再纠正”，都会导致状态不同步。
