---

name: grpc-golang description: "在 Go 中构建生产就绪的 gRPC 服务，包含 mTLS、流式传输和可观测性。用于使用 Buf 设计 Protobuf 契约或实现安全的服务间通信。" risk: safe source: self date_added: "2026-02-27"

gRPC Golang (gRPC-Go)

概述

在 Go 中设计和实现生产级 gRPC 服务的全面指南。涵盖使用 Buf 的契约标准化、通过 mTLS 的传输层安全，以及使用 OpenTelemetry 拦截器的深度可观测性。

使用场景

• 在 Go 中使用 gRPC 设计微服务通信。
• 使用 Protobuf 构建高性能内部 API。
• 实现流式工作负载（单向或双向）。
• 使用 Protobuf 和 Buf 标准化 API 契约。
• 为服务间认证配置 mTLS。

不适用场景

• 构建不需要 gRPC 的纯 REST/HTTP 公共 API。
• 修改遗留 .proto 文件且无法引入新 API 版本（如 api.v2）或确保向后兼容性。
• 管理服务网格流量路由（如 Istio/Linkerd），这超出了应用代码范围。

分步指南

1. 确认技术上下文：确定 Go 版本、gRPC-Go 版本，以及项目是否使用 Buf 或原始 protoc。
2. 确认需求：确定 mTLS 需求、负载模式（一元/流式）、SLO 和消息大小限制。
3. 规划模式：定义包版本（如 api.v1）、资源类型和错误映射。
4. 安全设计：为服务间认证实现 mTLS。
5. 可观测性：配置用于追踪、指标和结构化日志的拦截器。
6. 验证：在最终代码生成前始终运行 buf lint 和破坏性变更检查。

参考 resources/implementation-playbook.md 获取详细模式、代码示例和反模式。

示例

示例 1：定义服务和消息（v1 API）

syntax = "proto3";
package api.v1;
option go_package = "github.com/org/repo/gen/api/v1;apiv1";

service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
}

message User {
  string id = 1;
  string name = 2;
}

message GetUserRequest {
  string id = 1;
}

message GetUserResponse {
  User user = 1;
}

最佳实践

• ✅ 应该： 使用 Buf 通过 buf.yaml 和 buf.gen.yaml 标准化工具链和 lint。
• ✅ 应该： 始终在包路径中使用语义版本（如 package api.v1）。
• ✅ 应该： 对所有内部服务间通信强制使用 mTLS。
• ✅ 应该： 在所有流式处理器中处理 ctx.Done() 以防止资源泄漏。
• ✅ 应该： 将领域错误映射到标准 gRPC 状态码（如 codes.NotFound）。
• ❌ 不应该： 向 gRPC 客户端返回原始内部错误字符串或堆栈跟踪。
• ❌ 不应该： 每次请求创建新的 grpc.ClientConn；始终复用连接。

故障排除

• 错误：生成不一致：如果生成的代码与模式不匹配，运行 buf generate 并验证 go_package 选项。
• 错误：上下文超时：检查客户端超时设置，确保服务器在流式处理器中没有无限阻塞。
• 错误：mTLS 握手：确保 CA 证书在客户端和服务端都正确添加到 x509.CertPool。

限制

• 不涵盖服务网格流量路由（Istio/Linkerd 配置）。
• 不涵盖 gRPC-Web 或基于浏览器的 gRPC 集成。
• 假设 Go 1.21+ 和 gRPC-Go v1.60+；旧版本可能有不同的 API（如 grpc.Dial vs grpc.NewClient）。
• 不涵盖 L7 gRPC 感知负载均衡器配置（如 Envoy、NGINX）。
• 不涉及 Protobuf 模式注册表或超出 Buf lint 的大规模模式治理。

资源

• resources/implementation-playbook.md 获取详细模式、代码示例和反模式。
• Google API 设计指南
• Buf 文档
• gRPC-Go 文档
• OpenTelemetry Go 插桩

相关技能

• @golang-pro - gRPC 层之外的通用 Go 模式和性能优化。
• @go-concurrency-patterns - 流式处理器的高级 goroutine 生命周期管理。
• @api-design-principles - 编写 .proto 文件前的资源命名和版本策略。
• @docker-expert - 容器化 gRPC 服务和通过 Docker secrets 配置 TLS 证书注入。