gRPC拦截器使用教程与实战示例

在 Go 语言的 gRPC 开发中，拦截器是实现日志记录、身份认证、错误恢复等横切关注点的核心机制，文章深入讲解了一元拦截器（用于普通 RPC）和流式拦截器（适配客户端/服务端/双向流）的原理与编码实践，并通过真实可运行的代码示例展示了如何从零编写日志与 Token 认证拦截器，更进一步结合 go-grpc-middleware 库链式组合多个拦截器，让服务在保持业务逻辑纯净的同时，轻松获得可观测性、安全性与健壮性——无论你是刚接触 gRPC 的开发者，还是正在优化微服务架构的工程师，掌握拦截器都将显著提升你的工程效率与系统质量。

在 Go 语言中使用 gRPC 时，拦截器（Interceptor）是一种非常强大的机制，可以在请求处理前后插入通用逻辑，比如日志记录、认证、限流、监控等。gRPC 支持两种类型的拦截器：一元拦截器（Unary Interceptor）和流式拦截器（Streaming Interceptor）。下面详细介绍其实现方式与实际应用示例。

一元拦截器（Unary Interceptor）

一元拦截器用于拦截普通的 RPC 调用（即非流式调用），它本质上是一个中间件函数，包裹在服务方法执行前后。

// 定义一个简单的日志一元拦截器

func LoggingUnaryInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (resp interface{}, err error) {
    log.Printf("Received unary request: %s", info.FullMethod)
    resp, err = handler(ctx, req)
    log.Printf("Finished unary request: %s, error: %v", info.FullMethod, err)
    return resp, err
}

该拦截器在每次调用前打印请求方法名，在调用完成后输出执行结果。通过 handler(ctx, req) 触发实际的服务逻辑。

注册到 gRPC 服务器：

s := grpc.NewServer(grpc.UnaryInterceptor(LoggingUnaryInterceptor))

流式拦截器（Streaming Interceptor）

流式拦截器用于处理 gRPC 流（stream）类型的接口，如客户端流、服务端流或双向流。

// 定义一个基础的流式拦截器

func LoggingStreamInterceptor(srv interface{}, ss grpc.ServerStream, info *grpc.StreamServerInfo, handler grpc.StreamHandler) error {
    log.Printf("Received stream request: %s", info.FullMethod)
    err := handler(srv, ss)
    log.Printf("Finished stream request: %s, error: %v", info.FullMethod, err)
    return err
}

注意，流式拦截器无法直接读取消息内容，因为数据是通过 Recv() 和 Send() 在流上传输的。若需记录具体数据，可封装 ServerStream 实现包装器。

注册流式拦截器：

s := grpc.NewServer(grpc.StreamInterceptor(LoggingStreamInterceptor))

结合多个拦截器

实际项目中通常需要多个拦截器，例如同时做日志、认证和错误恢复。可以使用 go-grpc-middleware 库来组合多个拦截器。

// 安装中间件库

go get github.com/grpc-ecosystem/go-grpc-middleware

使用示例：

import "github.com/grpc-ecosystem/go-grpc-middleware"
import "github.com/grpc-ecosystem/go-grpc-middleware/auth"

s := grpc.NewServer(
    grpc.UnaryInterceptor(grpc_middleware.ChainUnaryServer(
        LoggingUnaryInterceptor,
        auth.UnaryServerInterceptor(myAuthFunc),
        recovery.UnaryServerInterceptor(),
    )),
    grpc.StreamInterceptor(grpc_middleware.ChainStreamServer(
        LoggingStreamInterceptor,
        auth.StreamServerInterceptor(myAuthFunc),
    )),
)

其中 myAuthFunc 是自定义认证函数，例如从 metadata 中提取 token 并验证。

实际应用场景示例

假设我们要实现一个基于 Token 的认证拦截器：

func myAuthFunc(ctx context.Context) (context.Context, error) {
    md, ok := metadata.FromIncomingContext(ctx)
    if !ok {
        return nil, status.Errorf(codes.Unauthenticated, "missing metadata")
    }
    tokens := md["token"]
    if len(tokens) == 0 {
        return nil, status.Errorf(codes.Unauthenticated, "missing token")
    }
    if tokens[0] != "secret" {
        return nil, status.Errorf(codes.PermissionDenied, "invalid token")
    }
    return ctx, nil
}

客户端调用时需带上 token：

ctx := metadata.AppendToOutgoingContext(context.Background(), "token", "secret")
resp, err := client.YourMethod(ctx, &request)

基本上就这些。拦截器让 gRPC 服务具备良好的可扩展性和维护性，合理使用能大幅提升系统健壮性。

今天关于《gRPC拦截器使用教程与实战示例》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！