能通并不代表能用——这句话在微服务架构中尤为深刻。许多团队在成功运行gRPC通信后，才发现实际中卡在连接假死、错误码丢失、流式阻塞等棘手问题上。问题往往不是代码写错了，而是关键参数未配置，或是代码生成逻辑本身就存在偏差。
protoc 生成代码报 undefined 或 cannot find package 的常见原因
这类问题，九成以上源于 go_package 声明与文件实际物理路径不匹配。并非插件缺失，也不是 proto 语法写错。
option go_package = "github.com/yourorg/user/v1";的含义是：生成的user_grpc.pb.go必须放置在项目目录下的github.com/yourorg/user/v1/路径中。在 Go Modules 模式下，该路径还需与go.mod中的module名前缀保持一致，否则编译时无法正确识别。- 使用
--go-grpc_opt=paths=source_relative参数，可以避免因从子目录执行protoc导致的路径错位问题。 - 多个 proto 文件共用同一个
go_package会引发编译冲突。例如user.proto和auth.proto都设置option go_package = "pb";，Go 会将其视为同一包，但结构体名重复，编译直接报错。 - 另一个常见失误：只执行
--go_out而不执行--go-grpc_out，导致NewXXXClient未定义；反之只执行--go-grpc_out，pb.XXXRequest类型又找不到。两个参数必须同时使用。
客户端 Dial 后调用卡住或连接不稳定
默认的 grpc.Dial 采用阻塞式建连，且不包含保活机制。当发生网络抖动、负载均衡超时、NAT 断连等情况时，连接状态变得不可知，表现为请求无法发出，Recv() 一直处于挂起状态。
- 必须添加
grpc.WithTimeout(5 * time.Second)，否则 DNS 解析缓慢或 TLS 握手失败时，等待几十秒也不罕见。 - 必须设置
grpc.WithKeepaliveParams(keepalive.ClientParameters{Time: 10 * time.Second})，否则空闲连接会被中间设备静默断开，而客户端仍以为连接存活。 - 生产环境应禁用
grpc.WithTransportCredentials(insecure.NewCredentials())，改用credentials.NewTLS(tlsConfig)。 *grpc.ClientConn是线程安全的，全局复用一个实例即可。不要每次 RPC 都调用Dial——TCP/TLS 开销很大，压测时连接数会迅速膨胀。
服务端返回 error，客户端却只收到 UNKNOWN
gRPC 默认将所有 error 转换为 status.Error(codes.Unknown, ...)，上游无法区分是用户不存在还是网络超时，导致重试、降级、监控全部失效。
- 服务端必须使用
status.Errorf(codes.NotFound, "user %d not found", id)，而不要用fmt.Errorf包装，否则状态码会丢失。 - 客户端收到 error 后，必须显式解包：
if st, ok := status.FromError(err); ok { switch st.Code() { case codes.NotFound: ... } }。 - 在拦截器中做日志或鉴权时，也要透传
status.Status，不能返回fmt.Errorf("xxx: %w", err)。 - 流式 RPC 更需注意：
Recv()返回非io.EOF的 error 才代表流异常终止，需要单独处理，不能当作普通读取结束。
流式 RPC 服务端实现后一发就卡死或 panic
流式方法的签名发生了变化，Server 参数类型不再是 context.Context，而是带 Send()/Recv() 的接口。如果直接在主线程循环发送数据，整个 handler 都会被阻塞。
- 服务端流（server streaming）必须启动 goroutine 发送，且每次
stream.Send()后检查 error：if err := stream.Send(msg); err != nil { return err }。 - 必须持续监听
stream.Context().Done()，一旦收到 cancel 或 deadline，立即退出循环，否则会造成 goroutine 泄漏。 - 在双向流中，不要假设客户端一定会及时调用
Recv()。发送前可以先通过stream.SetHeader()传递元数据试探，或者改用背压协议（如 ACK 流）。 - 别忘了嵌入
pb.UnimplementedXXXServer，否则调用未实现的方法会直接 panic，而不是返回 UNIMPLEMENTED 状态码。
最常被忽略的，其实是 go_package 路径一致性检查和 status.FromError 解包这两步。它们不会报编译错误，但上线后排查问题，往往需要花费三倍的时间。
