protobuf版本管理需严格遵循规范：go_package必须带版本号且不可复用目录，字段编号不可随意更改，reserved用于强制锁定编号段，高频字段应置于1–15编号段，新增字段须显式声明optional，删除字段仅能reserved，类型变更属破坏性操作，反序列化须禁用discardunknown以捕获未知字段。
Protobuf 版本管理不是“改完 .proto 再跑一遍 protoc”就能收工的事——它直接决定服务能不能启动、客户端会不会 panic、灰度升级会不会炸掉整条链路。
go_package 路径必须带版本号，且不能复用目录
这是最常被跳过的硬性门槛。如果 user.proto 里写的是 go_package = "example.com/api;api"，那 v2 升级时哪怕只加了一个字段，也绝不能把新 .proto 放进同一目录再生成一次。
- 必须改成
go_package = "example.com/api/v2;apiv2"，并把文件移到api/v2/user.proto -
protoc命令要显式指定模块根路径：protoc --go_out=paths=source_relative:./ --go-grpc_out=paths=source_relative:./ api/v2/user.proto - 否则生成的 Go 类型名（如
User）会和 v1 冲突，编译报duplicate definition - 更隐蔽的问题是：v1 客户端调用 v2 接口时，
Unmarshal可能成功，但字段值为零值，业务逻辑因未判空直接 panic
字段编号一改就废，reserved 不是注释而是锁
Protobuf 解析不看字段名，只认编号 + wire type。把 user_id = 1 改成 user_id = 2，旧客户端收到数据后，会把原本该填进编号 1 的字节流塞进编号 2 的字段（如果存在），或直接丢弃——没有错误提示，只有静默错乱。
Go语言（Golang）1.26.0版本提供 Go 官方 Windows amd64 MSI 安装包下载入口，版本号 1.26.0，可用于旧项目维护、兼容性测试和指定版本开发环境配置。
-
reserved是强制保留，不是可删的文档说明。例如：reserved 5, 10 to 15;，后续protoc编译会直接报错，如果有人试图分配编号 12 - 高频字段（如
id,status）务必压在 1–15 编号段，Go 生成代码不会帮你重排，编号越大，序列化后多占 1 字节（varint 编码规则） - 不要等删字段时才加
reserved，v1 设计阶段就要预留扩展段，比如reserved 16 to 20; - 19000–19999 是 Protobuf 内部保留段，绝对禁止使用
新增字段必须 optional，删除字段只能 reserved，类型变更基本等于重定义
v3 默认所有字段都是 optional，但这不等于你可以随便加字段。类型变更（如 int32 → int64）看似只是位宽变大，实际 wire encoding 规则不同，旧解析器会读错长度、解出垃圾值。
- 新增字段必须显式写
optional string filter = 3;（v3.12+ 支持），不能依赖默认行为——团队里有人用老插件生成，可能还是按 v2 语义处理 - 删除字段不能物理移除，只能加
reserved 7;和注释说明废弃原因 -
int32 → int64、string → bytes属于破坏性变更；string → optional string安全；repeated int32 → repeated int64也不安全 - oneof 新增分支可以，但把已有字段挪进 oneof 块会改变编码格式，等同于改编号
反序列化时别丢未知字段，XXX_Unrecognized 是你的灰度探测器
新版服务返回了 timeout = 5（编号 4），旧客户端没这字段，proto.Unmarshal 默认会静默丢弃。看起来一切正常，但你失去了关键信号：这个字段到底有没有被下游收到？
- 必须用
proto.UnmarshalOptions{DiscardUnknown: false}替代裸调proto.Unmarshal - 生成结构体里的
XXX_Unrecognized []byte字段（gogoproto 下可能是XXX_unrecognized）就是原始未知字段字节流 - 线上可统计
len(msg.XXX_Unrecognized) > 0的比例，作为 v2 灰度放量依据 - 禁用
DiscardUnknown后，若发现大量未知字段，说明客户端版本落后严重，得推动升级
真正麻烦的从来不是“怎么加个字段”，而是当三个服务用着四个版本的 .proto、两个团队共用一套 IDL、CI 流水线里混着 gogo/protobuf 和 google.golang.org/protobuf 时，你怎么让它们不互相咬住对方的 wire 格式。版本管理的终点，是让所有人对同一串二进制字节流，达成一致的解读。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
