生产环境gRPC需确保“稳通”而非仅“能通”：必须严格对齐go_package路径与文件存放位置、安装兼容插件并使用source_relative参数生成代码；连接须配置keepalive和超时；错误码须用status.Errorf返回并用status.FromError解包；流式RPC需检查Send错误和context状态；服务端必须嵌入UnimplementedServer防止panic。
生产环境里 gRPC 不是“能通就行”，而是“稳不通”——连接假死、错误码丢失、流式卡顿、proto 生成失败，这些问题往往在压测或上线后集中爆发。
protoc 生成代码总报错：路径、插件、go_package 三者必须对齐
报 cannot find package "xxx" 或 undefined: pb.XXX，基本不是语法错，而是生成路径和 import 路径不一致。核心约束有三点：
-
option go_package = "github.com/yourorg/user/v1"不是注释，它决定生成文件的包名和 import 路径，且必须与实际文件存放路径严格匹配（如user/v1/user_grpc.pb.go） - 必须同时安装两个插件：
protoc-gen-go和protoc-gen-go-grpc，且版本需兼容（v1.60+ 推荐用@latest） - 生成命令必须带
--go_opt=paths=source_relative和--go-grpc_opt=paths=source_relative，否则子目录下 proto 生成的 import 路径会错位
grpc.Dial 连接不设 keepalive 和 timeout 就等于裸奔
默认 grpc.Dial 是阻塞建连、无保活、无超时，网络抖动或服务重启后客户端会长期 hang 在 conn.Read，表现为“连接还在但调用无响应”。
- 必须加
grpc.WithTimeout(5 * time.Second)控制建连耗时，避免初始化卡死 - 必须启用 keepalive：
grpc.WithKeepaliveParams(keepalive.ClientParameters{Time: 10 * time.Second})，否则 NAT/LB 会在空闲 60 秒后静默断连，而客户端毫无感知 - 生产环境禁用
insecure.NewCredentials()；TLS 必须配credentials.NewTLS(tlsConfig)，否则握手失败只报connection refused
Unary RPC 错误码被吞掉：status.Errorf 和 status.FromError 缺一不可
服务端用 fmt.Errorf 或直接 return error，客户端收到的永远是 codes.Unknown，上游无法区分是业务失败还是网络故障。
立即学习“go语言免费学习笔记（深入）”；
- 服务端返回错误必须用
status.Errorf(codes.NotFound, "user %d not found", id)，不能包装成普通 error - 客户端收到 error 后，必须显式解包：
if st, ok := status.FromError(err); ok { switch st.Code() { case codes.NotFound: ... } } - 拦截器里也要透传
status.Status，否则中间件一包就丢状态码
服务端流式方法 panic 或卡死：Send() 错误没检查 + context 没监听
服务端流（rpc StreamLogs(LogRequest) returns (stream LogResponse)）最容易出问题：不检查 stream.Send() 返回 error，或忽略 stream.Context().Err()，会导致 goroutine 泄漏或缓冲区爆满后卡死。
- 每次
stream.Send(msg)后必须判断：if err := stream.Send(msg); err != nil { return err } - 循环中必须持续检查上下文：
if stream.Context().Err() != nil { return stream.Context().Err() } - 不要在 for 循环里无节制发送；客户端消费慢时，gRPC 内部缓冲会堆积，最终触发
transport: failed to write a frame
最常被跳过的其实是 UnimplementedXXXServer 的嵌入——只实现部分方法却不嵌入默认空实现，调用未实现方法直接 panic，而不是返回 codes.Unimplemented。这个坑不在日志里，只在第一次调用未覆盖方法时才暴露。
