gRPC 在 Go 中不是开箱即用的微服务框架，它只提供 RPC 通信能力；要构建可用的微服务，必须自己补全服务发现、负载均衡、健康检查、配置管理等能力。

定义 .proto 文件时必须显式启用 go_package 选项

不写 go_package 会导致生成的 Go 代码包路径与实际目录结构不一致，import 失败或引用到错误包。常见错误现象是编译报 undefined: pb.XxxServiceClient 或 cannot find package "xxx"。

• 必须在 .proto 文件顶部添加：syntax = "proto3"; option go_package = "github.com/yourorg/yourrepo/pb";
• go_package 值应与你运行 protoc 时的 --go_out 输出路径一致，且需匹配模块路径（go.mod 中的 module 名）
• 避免使用相对路径（如 ./pb）或空字符串，这会让 protoc-gen-go 推导出不可控的包名

服务端启动时需同时注册 HealthServer 并监听 /healthz

Kubernetes、Consul 等平台依赖健康端点做探活，但 gRPC 默认不暴露 HTTP 健康接口。直接用 grpc.HealthCheckService 注册后，仍需额外启动一个 HTTP server 转发 /healthz 请求到 gRPC health check 逻辑。

• 先调用 health.RegisterHealthServer(grpcServer, health.NewServer())
• 再起一个独立的 http.Server，用 grpc_health_v1.NewHealthClient(conn) 主动调用 Check() 实现 HTTP 健康响应
• 不要复用 gRPC 监听端口跑 HTTP（gRPC-Web 除外），HTTP/2 和 HTTP/1.1 混合容易触发连接复用冲突

客户端连接必须设置 WithTransportCredentials 或 WithInsecure

忽略传输层配置会导致连接失败，典型错误是 connection error: desc = "transport: Error while dialing dial tcp: operation was canceled" 或长时间卡在 DialContext。

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

立即学习“go语言免费学习笔记（深入）”；

• 本地开发用 grpc.DialContext(ctx, addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
• 生产环境必须用 grpc.WithTransportCredentials(credentials.NewTLS(tlsConfig))，且 tlsConfig.ServerName 需与证书 SAN 匹配
• 禁用 WithInsecure 后未配 TLS 会直接 panic，错误信息为 credentials: no credentials available

流式 RPC 的 context 生命周期极易出错

客户端取消 context 不等于服务端立即停止发送，服务端若继续写入已关闭的 stream，会触发 rpc error: code = Canceled desc = context canceled 或 write: broken pipe。

• 服务端每次 Send() 前必须检查 stream.Context().Err() != nil
• 客户端读取 Recv() 时需用 if err == io.EOF { break } 判断流结束，不能只靠 err != nil
• 不要在流处理 goroutine 中直接传入原始请求 context，应基于它派生带超时的子 context 控制单次 Send/Recv

真正难的不是写通第一个 gRPC 服务，而是让多个服务在不同网络条件下稳定互调——超时传递、deadline 透传、错误码映射、重试策略这些细节，往往比协议定义本身更消耗调试时间。