必须确保go_package路径与物理目录一致且匹配go.mod前缀，客户端须用status.FromError解包错误码，流式RPC需单独处理非io.EOF错误并启用KeepAlive保活。
能通不等于能用——微服务里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就是 undefined；反过来只跑--go-grpc_out，pb.XXXRequest类型就找不到
客户端 Dial 后调用卡住或“稳不通”
默认 grpc.Dial 是阻塞建连 + 零保活机制，网络抖动、LB 超时、NAT 断连后连接状态不可知，表现就是请求发不出、Recv() 一直 hang。
- 必须加
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, ...)，上游没法区分是用户不存在还是网络超时，重试、降级、监控全失效。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
立即学习“go语言免费学习笔记（深入）”；
- 服务端必须用
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，不能 returnfmt.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 解包这两步——它们不报编译错误，但上线后查问题要花三倍时间。
