protobuf默认序列化不适用于文件传输，需封装自定义帧协议（含magic+payloadlen）、分离元信息与文件数据、显式赋值关键字段，并确保go_package路径一致。
直接用 protoc 生成 Go 代码后调用 proto.Marshal 和 proto.Unmarshal 就能完成基础数据交换，但实际用于文件传输时，光靠默认序列化远远不够——它不处理帧边界、不校验完整性、不支持流式分块，更没法和 TCP 连接生命周期对齐。
proto.Marshal 不能直接发 TCP，必须封装成帧
Protobuf 本身只负责把结构体转成二进制字节流，不带长度头、无 Magic 标识、无法区分多个消息粘包。TCP 是字节流协议，proto.Unmarshal 拿到的可能是半条消息、两条拼在一起，或带多余垃圾字节。
- 必须在 Protobuf payload 外加自定义帧头（如 Magic + PayloadLen），服务端按长度读取再解包
- 推荐在
frame/frame.go中封装ReadFrame/WriteFrame，内部调用io.ReadFull避免部分读 - 别用
bufio.Reader直接读proto.Message：它不知道消息边界，容易阻塞或 panic
文件元信息与内容必须分离设计
一个 FileUploadRequest 消息如果把整个文件内容塞进 bytes 字段，会瞬间吃光内存、触发 GC 压力，且无法断点续传。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 元信息（文件名、大小、CRC32、offset）走 Protobuf 消息，例如
UploadStart或ChunkHeader - 真实文件数据走裸
conn.Write()，跳过 Protobuf 序列化开销，实现零拷贝（可用io.Copy+file的ReadAt） - Protobuf 消息里字段编号别乱排：
file_size = 1、offset = 2、crc32 = 3这类高频字段放前面，提升编码效率
go_package 路径错位会导致 import 失败或运行时 panic
生成的 *.pb.go 文件顶部有 import "github.com/xxx/yyy"，这个路径必须和 go.mod 的 module 名、实际文件存放路径完全一致，否则编译通过但运行时报 proto: can't find field 或类型注册失败。
-
.proto文件中必须显式写option go_package = "github.com/yourorg/fs_transfer/protos"; - 生成命令必须带
--go_out=paths=source_relative:.，否则路径会被硬编码为绝对路径 - 检查生成文件里的
proto.RegisterMapType调用是否包含你定义的 message，缺失说明go_package解析失败
Proto3 枚举和默认值在传输中容易被静默丢弃
Proto3 默认所有字段可选，未设置的 enum、int32、string 在 wire 上不占字节；接收方拿到的是零值（0、""），不是“未设置”。这对文件传输指令是危险的——比如 Cmd 枚举没设值，服务端就收不到有效指令。
- 用
oneof显式约束互斥状态，例如oneof command { UploadStart upload_start = 1; DownloadAck download_ack = 2; } - 关键控制字段（如
stream_id、cmd）不要依赖默认值，Client 端必须显式赋值 - 调试时用
proto.CompactTextString(msg)打印原始结构，比直接 log 字段更可靠
真正卡住人的从来不是 protoc 命令会不会跑，而是帧怎么切、零值怎么判、内存怎么控——这些细节藏在 frame.go 和 file_ops_advanced.go 的几百行里，而不是 *.pb.go 自动生成的几千行中。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
