proto文件必须写option go_package，否则生成的Go代码包路径错误导致依赖无法识别；需同时使用protoc-gen-go和protoc-gen-go-grpc插件；gRPC服务端须用net.Listen+grpc.NewServer并显式启用h2c；字段编号变更破坏兼容性。
proto文件定义必须写option go_package
不加这行，生成的Go代码包路径会出错，go mod tidy识别不了依赖，import时直接报cannot find package。它不是可选配置，而是Go侧生成代码的定位依据。
常见错误现象：生成的user.pb.go里包名是user，但实际想放到./pb/user目录下——没设option go_package时，protoc默认按文件路径推导，结果和模块路径对不上。
-
option go_package = "example.com/pb/user;user"：前半段是导入路径（对应go.mod里的module名），后半段是包名（生成文件顶部的package user） - 若用
go mod init example.com/pb，那go_package必须匹配这个根路径，否则go build失败 - 多个.proto共用一个Go包时，所有文件的
go_package值必须一致，否则生成的.pb.go互相import会循环或缺失
生成代码必须同时用protoc-gen-go和protoc-gen-go-grpc
只跑protoc --go_out=.，你只会得到消息结构体和Marshal/Unmarshal方法，没有服务注册入口、没有客户端桩函数——RegisterUserServiceServer和NewUserServiceClient根本不存在，gRPC服务起不来。
典型报错：undefined: RegisterUserServiceServer 或 cannot use &server{} (type *server) as type UserServiceServer in argument to RegisterUserServiceServer。
立即学习“go语言免费学习笔记（深入）”；
- 两个插件缺一不可：
protoc-gen-go负责.pb.go（数据），protoc-gen-go-grpc负责_grpc.pb.go（RPC） - 命令要带
--go_opt=paths=source_relative和--go-grpc_opt=paths=source_relative，否则生成的import路径可能是绝对路径，CI里编译失败 - Go 1.21+环境下，推荐用
google.golang.org/protobuf/cmd/protoc-gen-go@v1.34+和google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.5+，旧版github.com/golang/protobuf已废弃
Go服务端必须用net.Listen + grpc.NewServer，不能套http.ListenAndServe
gRPC基于HTTP/2，而http.ListenAndServe只支持HTTP/1.1，Python/Node.js客户端连上来直接被拒绝，错误常是StatusCode.UNAVAILABLE或connection refused，日志里却没明显报错。
关键点不在“能不能跑起来”，而在“能不能被其他语言正确协商协议”。HTTP/2明文（h2c）模式必须显式启用，否则客户端默认走TLS握手，服务端没配证书就静默断连。
- 启动代码必须是：
l, _ := net.Listen("tcp", ":50051"); s := grpc.NewServer(); s.Serve(l) - 如果要用明文gRPC（开发阶段），需加
grpc.WithTransportCredentials(insecure.NewCredentials())，否则Python客户端即使设insecure=True也连不上 - 跨语言调用前，先用
grpcurl -plaintext localhost:50051 list验证服务是否暴露了接口，比写客户端更快定位问题
字段编号改了就破坏兼容性，字段名改不影响
Protobuf序列化只认字段编号（=1、=2），不认字段名。Go里把user_id改成userId，Python那边还是用user_id，只要编号不变，反序列化完全正常——但一旦把int32 id = 2改成int32 id = 3，旧客户端收到新服务端发来的数据就会丢字段，甚至panic。
这是最容易被忽略的隐性坑：团队协作中有人手改.proto字段编号，本地测试全过，上线后其他语言客户端开始报missing field或解析出零值。
- 新增字段必须用新编号，且设
optional（proto3默认就是optional）；删除字段不能重用旧编号，要留空 - 字段类型变更（如
string→bytes）属于不兼容改动，即使编号相同也会解码失败 - 建议在CI里加一步：
protoc --encode="User" user.proto ，确认二进制能round-trip
