必须加帧头（magic+payloadlen）才能安全使用protobuf传输，否则tcp必然粘包；大文件需分离元信息与原始数据；go_package路径须与module严格一致；proto3枚举未赋值将静默为0，关键字段须强制赋值并校验。
直接发 proto.Marshal 到 TCP 连接里，90% 以上概率出问题——不是 Protobuf 不行，是没加帧头。
TCP 发 Protobuf 必须加帧头，否则必然粘包
Protobuf 只负责把结构转成二进制字节流，不带长度、不带边界。TCP 是字节流协议，conn.Write(proto.Marshal(msg)) 发出去的是一串裸数据，接收端用 io.ReadFull 或 bufio.Reader.Read 读，要么阻塞，要么读到一半就返回，解出来的 proto.Unmarshal 直接 panic 或静默失败。
- 帧头至少含两个字段：
Magic（比如0x12345678，用于快速识别协议） +PayloadLen（4 字节 uint32，告诉接收方接下来该读多少字节） - 封装
WriteFrame(conn net.Conn, msg proto.Message)：先算data := proto.Marshal(msg)，再拼帧头（Magic + len(data)），最后conn.Write() - 封装
ReadFrame(conn net.Conn) ([]byte, error)：先读 8 字节帧头，校验 Magic，再按PayloadLen调用io.ReadFull(conn, payload)，确保读满 - 别在帧头里塞太多东西——版本、Cmd、StreamID 可以加，但总长建议 ≤16 字节；否则小消息开销占比过高，反而拖慢吞吐
大文件传输必须分离元信息和原始数据
把整个文件塞进 bytes 字段，等于让 Protobuf 序列化器扛下全部内存压力。100MB 文件 = 100MB Go 内存 + GC 尖峰 + 多次拷贝。这不是设计缺陷，是用法错。
Go语言（Golang）1.26.0版本提供 Go 官方 Windows amd64 MSI 安装包下载入口，版本号 1.26.0，可用于旧项目维护、兼容性测试和指定版本开发环境配置。
- 元信息走 Protobuf：
ChunkHeader定义filename、offset、crc32、chunk_size等字段，高频字段编号放前面（如offset = 1）利用 Varint 压缩 - 原始数据绕过 Protobuf：收到
ChunkHeader后，直接用io.Copy(conn, fileReader)或conn.Write(chunkData)发送，零拷贝 - 接收端先
ReadFrame解出ChunkHeader，再按chunk_size读原始数据，不经过proto.Unmarshal
go_package 路径错位会导致运行时静默失败
生成的 *.pb.go 文件顶部 import 路径和 go.mod module 名不一致，编译能过，但 proto.Unmarshal 会报 proto: can't find field 或直接静默失败——没有 panic，也没有日志，字段全为零值。
- 生成命令必须带
--go_out=paths=source_relative:.，否则路径硬编码成绝对路径，CI 构建或换机器必崩 - 检查生成文件里是否有
proto.RegisterMapType(&YourMessage{}, "")，缺失说明go_package解析失败，不是插件没装好 -
option go_package = "github.com/yourorg/yourrepo/pb";中的路径必须与go.mod第一行 module 完全一致（包括大小写）
Proto3 枚举未赋值会静默变成 0，关键字段必须强制设值
Proto3 默认所有字段 optional，Cmd 枚举没设值，wire 上一个字节都不占，接收方拿到的是 0（即第一个枚举值），不是“未设置”。这对指令类消息极其危险——比如 Cmd_DOWNLOAD 没赋值，对方收到 Cmd_UPLOAD。
- 用
oneof显式约束互斥状态：oneof command { UploadStart upload_start = 1; DownloadRequest download_request = 2; } - 关键字段（如操作类型、状态码）不要依赖默认值，发送前强制赋值：
req.Cmd = pb.Cmd_UPLOAD_START - 服务端收到消息后，对关键枚举字段做显式校验：
if req.Cmd == pb.Cmd(0) { return errors.New("missing cmd") }
真正容易被忽略的不是语法细节，而是“Protobuf 本身不解决网络传输问题”这个前提——所有粘包、丢数据、解不出结构的问题，根源都在帧协议缺位，而不是序列化逻辑写错了。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
