Go语言构建gRPC服务的隐性坑包括：proto需显式设go_package并匹配import路径；Server须提前注册service且方法签名严格一致；客户端Dial需配置匹配的TransportCredentials、WithBlock和超时；流式RPC中context生命周期须谨慎管理；健康检查等运维功能不可省略。
Go 语言构建 gRPC 服务本身不难，难的是从零开始时踩的那些隐性坑：协议定义没对齐、生成代码路径错乱、TLS 配置漏掉 ServerTransportCredentials、grpc.Dial 用 insecure 却忘了关掉 WithTransportCredentials……这些错误不会报语法错，但连不上、超时、或返回空响应。
proto 文件必须用 go_package 显式声明包路径
很多人写完 service.proto 就直接 protoc --go_out=.，结果生成的 Go 文件里包名是 main 或空字符串，导致 import 失败或类型无法识别。
必须在 .proto 文件顶部加：
option go_package = "github.com/yourorg/yourproject/pb";
然后执行时指定输出目录和模块根路径：
立即学习“go语言免费学习笔记（深入）”；
protoc --go_out=. --go-grpc_out=. --go_opt=paths=source_relative --go-grpc_opt=paths=source_relative service.proto- 确保当前目录是 Go module 根（有
go.mod），否则go_package路径无法被 Go 工具链解析 - 如果 proto 在子目录（如
api/v1/），go_package值应与实际 import 路径一致，不能只写包名
grpc.Server 启动前必须注册所有 service 实现
常见错误是只调用 pb.RegisterYourServiceServer(srv, &server{})，但忘了 srv.Serve(lis) 前 server 结构体字段未初始化，或方法签名与 proto 定义不匹配（比如少了个 context.Context 参数）。
检查点：
- 实现结构体的方法签名必须严格匹配生成的
UnimplementedYourServiceServer接口，例如：func (*MyServer) SayHello(ctx context.Context, req *pb.HelloRequest) (*pb.HelloResponse, error) - 注册必须在
srv.Serve()之前完成，且不能重复注册同一 service - 若使用拦截器（如
UnaryInterceptor），需在grpc.NewServer()时传入，而不是注册后动态添加
grpc.Dial 连接失败的三大高频原因
客户端连不上服务端，90% 出现在这里。不是网络不通，而是配置不一致。
典型错误组合：
- 服务端启用了 TLS（
credentials.NewServerTLSFromCert），但客户端仍用grpc.WithInsecure()—— 必须改用grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(...)) - 服务端监听
localhost:50051，客户端却 dial127.0.0.1:50051（或反过来），在某些系统上 DNS 解析或 IPv6/IPv4 混合时会失败 - 忘记加
grpc.WithBlock()或超时控制，导致Dial返回nilconn + 非空 error，但后续调用 panic："rpc error: code = Unavailable desc = connection closed before server preface received"
安全写法示例：
conn, err := grpc.Dial("localhost:50051",
grpc.WithTransportCredentials(insecure.NewCredentials()),
grpc.WithBlock(),
grpc.WithTimeout(5*time.Second),
)
流式 RPC 的 context 生命周期容易被忽略
无论是 client-stream、server-stream 还是 bidi-stream，每个 stream 的 Context() 是独立的，且一旦 stream 关闭，该 context 就会被 cancel。拿它做跨请求缓存或后台 goroutine 会导致 panic 或资源泄漏。
正确做法：
- 不要在 stream handler 外部保存
stream.Context()；需要长期存活的 context，请用context.Background()或显式传入父 context - server-stream 中，如果在
Send()前做了耗时操作（如 DB 查询），记得检查stream.Context().Err() != nil，避免向已关闭的 stream 发送数据 - bidi-stream 的循环收发逻辑中，必须同时监听
Recv()和stream.Context().Done()，否则可能阻塞在Recv()上永远不退出
最常被跳过的细节：gRPC 的健康检查、反射服务、Prometheus 指标注入，这些不是“可选功能”，而是上线前必须确认是否启用、是否暴露在生产端口——否则运维连服务存不存在都查不到。
