golang-grpc

Name: golang-grpc
Author: samber

Go gRPC 最佳实践

将gRPC视为纯传输层——与业务逻辑分离。官方Go实现是google.golang.org/grpc。

本技能并非详尽无遗。请参考库文档和代码示例获取更多信息。Context7可作为发现平台提供帮助。对于Go包文档、版本、符号和已知漏洞，→ 参见samber/cc-skills-golang@golang-pkg-go-dev技能。

快速参考

关注点	包/工具
服务定义	`protoc` 或 `buf` 配合 `.proto` 文件
代码生成	`protoc-gen-go`, `protoc-gen-go-grpc`
错误处理	`google.golang.org/grpc/status` 配合 `codes`
丰富错误详情	`google.golang.org/genproto/googleapis/rpc/errdetails`
拦截器	`grpc.ChainUnaryInterceptor`, `grpc.ChainStreamInterceptor`
中间件生态	`github.com/grpc-ecosystem/go-grpc-middleware`
测试	`google.golang.org/grpc/test/bufconn`
TLS / mTLS	`google.golang.org/grpc/credentials`
健康检查	`google.golang.org/grpc/health`

Proto 文件组织

按领域组织，使用版本化目录（proto/user/v1/）。始终使用Request/Response包装消息——裸类型如string无法后续添加字段。使用buf generate或protoc生成。

Proto 与代码生成参考

服务器实现

实现健康检查服务（grpc_health_v1）—— Kubernetes探针需要它来确定就绪状态
使用拦截器处理横切关注点（日志、认证、恢复）——保持业务逻辑清晰
使用GracefulStop()并配合超时回退到Stop()——在防止挂起的同时排空正在进行的RPC
在生产环境中禁用反射——它会暴露完整的API表面

srv := grpc.NewServer(
    grpc.ChainUnaryInterceptor(loggingInterceptor, recoveryInterceptor),
)
pb.RegisterUserServiceServer(srv, svc)
healthpb.RegisterHealthServer(srv, health.NewServer())

go srv.Serve(lis)

// 收到关闭信号时：
stopped := make(chan struct{})
go func() { srv.GracefulStop(); close(stopped) }()
select {
case <-stopped:
case <-time.After(15 * time.Second):
    srv.Stop()
}

拦截器模式

func loggingInterceptor(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) {
    start := time.Now()
    resp, err := handler(ctx, req)
    log.Printf("method=%s duration=%s code=%s", info.FullMethod, time.Since(start), status.Code(err))
    return resp, err
}

客户端实现

复用连接——gRPC在单个HTTP/2连接上多路复用RPC；每个请求新建连接浪费TCP/TLS握手
为每次调用设置截止时间（context.WithTimeout）——没有截止时间时，慢速上游会无限期挂起goroutine
使用round_robin配合无头Kubernetes服务，通过dns:///方案
通过metadata.NewOutgoingContext传递元数据（认证令牌、追踪ID）

conn, err := grpc.NewClient("dns:///user-service:50051",
    grpc.WithTransportCredentials(creds),
    grpc.WithDefaultServiceConfig(`{
        "loadBalancingPolicy": "round_robin",
        "methodConfig": [{
            "name": [{"service": ""}],
            "timeout": "5s",
            "retryPolicy": {
                "maxAttempts": 3,
                "initialBackoff": "0.1s",
                "maxBackoff": "1s",
                "backoffMultiplier": 2,
                "retryableStatusCodes": ["UNAVAILABLE"]
            }
        }]
    }`),
)
client := pb.NewUserServiceClient(conn)

错误处理

始终使用status.Error返回gRPC错误，并指定具体状态码——原始error会变成codes.Unknown，客户端无法据此采取行动。客户端根据状态码决定重试、快速失败还是降级。

状态码	使用场景
`InvalidArgument`	输入格式错误（缺少字段、格式错误）
`NotFound`	实体不存在
`AlreadyExists`	创建失败，实体已存在
`PermissionDenied`	调用者缺少权限
`Unauthenticated`	令牌缺失或无效
`FailedPrecondition`	系统未处于所需状态
`ResourceExhausted`	速率限制或配额超限
`Unavailable`	临时问题，可安全重试
`Internal`	意外错误
`DeadlineExceeded`	超时

// ✗ 糟糕——调用方收到codes.Unknown，无法决定是否重试
return nil, fmt.Errorf("user not found")

// ✓ 良好——具体状态码让客户端采取适当行动
if errors.Is(err, ErrNotFound) {
    return nil, status.Errorf(codes.NotFound, "user %q not found", req.UserId)
}
return nil, status.Errorf(codes.Internal, "lookup failed: %v", err)

对于字段级验证错误，通过status.WithDetails附加errdetails.BadRequest。

流式处理

模式	使用场景
服务器流式	服务器发送序列（日志追踪、结果集）
客户端流式	客户端发送序列，服务器响应一次（文件上传、批量操作）
双向流式	双方独立发送（聊天、实时同步）

优先使用流式而非大型单条消息——避免单条消息大小限制并降低内存压力。

func (s *server) ListUsers(req *pb.ListUsersRequest, stream pb.UserService_ListUsersServer) error {
    for _, u := range users {
        if err := stream.Send(u); err != nil {
            return err
        }
    }
    return nil
}

测试

使用bufconn进行内存连接，无需网络开销即可测试完整的gRPC栈（序列化、拦截器、元数据）。始终测试错误场景是否返回预期的gRPC状态码。

测试模式与示例

安全

生产环境必须启用TLS——凭据通过元数据传输
对于服务间认证，使用mTLS或委托给服务网格（Istio、Linkerd）
对于用户认证，实现credentials.PerRPCCredentials并在认证拦截器中验证令牌
生产环境应禁用反射以防止API发现

性能

设置	目的	典型值
`keepalive.ServerParameters.Time`	空闲连接的心跳间隔	30s
`keepalive.ServerParameters.Timeout`	心跳确认超时	10s
`grpc.MaxRecvMsgSize`	覆盖4MB默认值以支持大负载	16 MB
连接池	高负载流式传输的多个连接	4个连接

大多数服务不需要连接池——在增加复杂性之前先进行性能分析。

常见错误

错误	修复
返回原始`error`	变成`codes.Unknown`——客户端无法决定是否重试。使用`status.Errorf`指定具体状态码
客户端调用没有截止时间	慢速上游无限期挂起。始终使用`context.WithTimeout`
每个请求新建连接	浪费TCP/TLS握手。创建一次，复用——HTTP/2多路复用RPC
生产环境启用反射	让攻击者枚举所有方法。仅在开发/预发布环境启用
对所有错误使用`codes.Internal`	错误的状态码破坏客户端重试逻辑。`Unavailable`触发重试；`InvalidArgument`不会
裸类型作为RPC参数	无法向`string`添加字段。包装消息允许向后兼容的演进
缺少健康检查服务	Kubernetes无法确定就绪状态，部署期间杀死Pod
忽略上下文取消	调用方放弃后长时间操作仍在继续。检查`ctx.Err()`