跨语言gRPC调用失败主因是契约未对齐：protoc需同时指定--go_out和--go-grpc_out，且必须加paths=source_relative选项、显式声明syntax="proto3"和go_package，服务端须用net.Listen+grpc.Server.Serve，客户端连接参数（如明文/安全通道）须与服务端严格匹配。
跨语言调用失败，90% 是 protoc 生成代码不全、服务端没跑在纯 HTTP/2、或 .proto 定义在不同语言间不一致。不是 Go 不行，是契约没对齐。
protoc 命令漏掉 --go-grpc_out 就等于没写服务
只执行 protoc --go_out=. user.proto，只会生成 UserRequest 和 UserResponse 这类消息结构体，但不会生成 RegisterUserServiceServer 函数和 NewUserServiceClient 类型——服务端没法注册，客户端根本连不上。
- 必须同时指定两个插件：
protoc --go_out=. --go-grpc_out=. user.proto - Go 1.21+ 推荐加路径选项：
--go_opt=paths=source_relative --go-grpc_opt=paths=source_relative，避免生成绝对路径导入 -
option go_package = "example.com/pb";必须写在.proto文件顶部，否则生成的包路径错乱，import直接报错
Go 服务端监听方式错了，Python/Java 客户端就静默失败
gRPC 要求纯 HTTP/2，不能塞进 http.ServeMux，也不能用 http.ListenAndServe。常见错误是把 grpc.Server 当成普通 handler 注册，结果客户端收不到任何响应，只看到 rpc error: code = Unavailable desc = transport is closing。
- 正确写法：用
net.Listen("tcp", ":50051")得到 listener，再传给server.Serve(lis) - 开发环境务必显式启用明文支持：
grpc.NewServer(grpc.Creds(credentials.NewInsecure())) - 别写
grpc.WithInsecure()—— 这个选项已废弃，新版 grpc-go 里不存在
proto3 语法不统一，字段值在 Java/Python 里直接消失
Go 默认兼容 proto3，但 Java 或 Python 项目若没声明 syntax = "proto3";，或用了旧版插件，会导致空字符串、0 值字段被跳过，或者枚举未初始化直接 panic。
立即学习“go语言免费学习笔记（深入）”；
- 所有
.proto文件第一行必须是syntax = "proto3"; - 枚举第一个值必须显式设为 0：
UNKNOWN = 0;，否则 Go 默认用 0，Java 可能认为字段未设置而抛IllegalArgumentException - 禁用
optional（proto3 原生不支持），除非所有语言都开启experimental_allow_proto3_optional并版本对齐 -
repeated string tags = 1;没问题，但map<string, string> metadata = 2;跨语言比对容易失败——Go map 无序，Java HashMap 顺序不保证
客户端连接参数不匹配，连都连不上
Python 写 grpc.secure_channel 但 Go 端没配 TLS，或 Java 客户端忘了 .usePlaintext()，都会卡在连接建立阶段，日志里往往只有超时或 connection refused。
- Python 客户端开发环境必须用：
grpc.insecure_channel('localhost:50051') - Java 客户端对应写：
ManagedChannelBuilder.forAddress("localhost", 50051).usePlaintext() - 验证是否通 HTTP/2：用
grpcurl -plaintext localhost:50051 list，能列出服务名才算真正就绪 - 别信
curl -v http://localhost:50051—— gRPC 不走 HTTP/1.1，这种请求必然失败，不代表服务没起来
最容易被忽略的是：不同语言生成代码所依赖的 protoc 版本和插件版本必须对齐。比如 protoc 24.x 配 grpc-go v1.60+，但 Python 的 grpcio-tools 若还是 1.47，生成的 client stub 就可能缺方法或字段映射错位——这种问题不会编译报错，只会在运行时返回 invalid message 或 unknown field。
