用途:帮助 Go 开发者把 gRPC 服务从基础用法提升到生产级实践,核心是“契约优先”——把 proto 当作 API 来管理。
主要能力与要点:
- Proto 设计:包名带版本(如 payment.v1),破坏性变更升为 v2;不复用或重编号字段标签,删除的标签用 reserved 保留;每个 RPC 使用独立的 Request/Response 消息;用 buf 或固定版本 protoc 生成并提交生成代码。
- 错误处理:返回 status.Error,在统一位置把领域错误映射为语义正确的状态码(NotFound、AlreadyExists、InvalidArgument、FailedPrecondition、Unauthenticated、PermissionDenied、Unavailable、Internal 等);客户端用 status.FromError 读取码,不解析消息文本;Internal 不泄露内部错误细节。
- 超时:客户端每次调用都设置 deadline(context.WithTimeout),服务端通过 context 继承该 deadline,并在昂贵操作前检查 ctx.Err(),把 ctx 传递到下游调用以传播取消。
- 拦截器:用 grpc.ChainUnaryInterceptor 串联恢复、日志、鉴权等横切关注点,顺序为恢复最外层、再可观测性、再鉴权;流式 RPC 需对应的 StreamInterceptor。
- 流式传输:服务端流用于大结果集,循环 stream.Send,出错返回非 nil 错误;客户端/双向流仅在协议确需时使用;始终在 stream.Context().Done() 上终止。
- 生产部署:注册 grpc.health.v1 健康服务供负载均衡使用,按策略决定是否开启 reflection;收到取消信号后先 GracefulStop,超时(如 10 秒)后强制 Stop。
使用方式:按上述规则编写 proto 与 Go 服务端/客户端代码,配合验证清单逐项检查。
限制:资料未提供具体安装命令、依赖版本、性能数据或收费信息;示例代码为示意,实际需结合项目调整。