Protobuf 字段变更必须遵守 wire 兼容性规则：新增字段需用 optional 或 repeated 且编号不复用，删除字段须 reserved 而非删除整行，改类型或复用编号必破坏兼容，重命名字段允许但编号不可变；go_package 必须显式含版本号并物理隔离 proto 文件；HTTP API 版本须用路径前缀（如 /v1/、/v2/）隔离，禁止 query/header 路由；客户端必须使用与服务端一致的 proto 版本生成代码，上线前需 CI 校验 breaking change。
Protobuf 字段变更必须遵守 wire 兼容性规则
gRPC 接口升级翻车最多的地方，是以为改个字段名、加个 optional、删个不用的字段就没事——其实 wire 层根本不管 Go struct 名或 JSON tag，只认字段编号（tag number）和 wire type。一旦破坏，老客户端发来的请求或收到的响应就会直接 panic，报错类似 proto: wrong wireType。
- 新增字段：必须用
optional（proto3）或repeated，且 tag 编号不能复用已存在的编号 - 删除字段：只能写
reserved 5;，不能删掉整行；否则旧客户端传过来的该字段数据会被误解析为下一个字段 - 改类型：比如
int32 user_id = 1;改成string user_id = 1;，wire type 从 varint 变成 length-delimited，必然解析失败 - 重命名字段：可以，但 tag 编号绝对不能变；生成的 Go struct 字段名不影响 wire 层，
json:"user_id"也不影响 - 验证手段：用
protoc --descriptor_set_out=api.desc api/v1/user.proto导出 descriptor，再跑buf check breaking --against api.desc api/v2/user.proto
go_package 路径必须显式带版本号并分目录存放
Protobuf 生成代码时最隐蔽的坑，是不同版本的 .proto 文件用了相同或冲突的 go_package，导致编译报 duplicate definition，或者运行时 interface{} → *v2.User 断言失败——因为 Go 认为那是两个完全无关的类型，哪怕字段一模一样。
立即学习“go语言免费学习笔记（深入）”；
-
go_package必须显式声明，且路径含版本号，例如go_package = "example.com/api/v1;apiv1"，不能省略v1或写成v2后还放在同一目录 - v1 和 v2 的
.proto文件必须物理隔离：如api/v1/user.proto和api/v2/user.proto，避免protoc生成时覆盖或混用 import - 生成命令要匹配路径：用
protoc --go_out=paths=source_relative:./ --go-grpc_out=paths=source_relative:./ api/v1/user.proto，确保生成文件的package apiv1和 import 路径一致 - 服务端注册多个版本时，绝不能把
v1.UserServiceServer和v2.UserServiceServer注册到同一个*grpc.Server实例里——gRPC 不支持 path-based 路由，必须靠反向代理（如 Envoy）按:path或 header 分流到不同进程
HTTP API 版本路径必须用前缀隔离，不能靠 query 或 header 路由
很多团队试图用 /users?version=v2 或 Accept: application/json; version=2 做版本路由，结果监控打点失效、Istio VirtualService 无法精确切流、日志分析全乱套——因为网关层根本看不到 query 参数语义，header 又没法做连接池复用和 TLS 终止策略。
- 正确方式：/v1/users 和 /v2/users 是两个完全独立的 endpoint，可分别部署、灰度、下线
- Go 路由器建议按版本实例化：用
chi.NewRouter()分别建v1Router和v2Router，避免if version == "v2"这类条件分支污染 handler - 返回响应时主动写
X-API-Version: 2，让客户端明确感知当前生效版本，而不是靠猜 - 错误码含义必须锁定：比如 /v1 返回 404 表示“用户不存在”，/v2 不能改成 400，否则老前端会静默失败
客户端调用必须与服务端 protobuf 版本严格匹配
客户端用 v1 的 .proto 生成代码去连 v2 服务端，哪怕只是新增了一个字段，只要没设默认值或没处理未知字段，就可能触发 unmarshal error；反过来，v2 客户端连 v1 服务端，遇到缺失字段也会 panic——这不是 gRPC 的问题，而是 Protobuf wire 兼容性边界被越过了。
- 关键原则：客户端必须使用和服务端部署版本一致的
.proto文件生成代码，不能“用最新版生成，兼容旧服务” - 上线前强制校验：CI 流程中加入
buf check breaking，对比当前 PR 的 proto 和主干上已发布的 descriptor - 灰度发布时，先升级服务端，等所有客户端完成 v2 SDK 升级后，再下线 v1 接口；不要指望“服务端兼容旧客户端”能兜底所有 case
- 最容易被忽略的一点：
google.api.HttpRule（gRPC-Gateway 场景）里的pattern也属于契约一部分，/v1/users/{id} 改成 /v2/users/{user_id} 就算路径前缀对了，也是不兼容变更
