gRPC拦截器使用详解与实战教程

gRPC拦截器是Go语言中实现RPC调用前后统一逻辑处理的核心机制，尤其在服务端通过`grpc.UnaryServerInterceptor`可轻松集成日志记录、身份鉴权、错误恢复、监控限流等关键能力，既避免了业务代码中大量重复的横切逻辑，又显著提升了服务的可维护性、可观测性与健壮性；本文手把手带你从拦截器原理、函数签名、自定义实现到链式注册（支持多拦截器组合），再到真实场景落地，助你快速掌握这一gRPC工程化必备技能。

在Go语言中使用gRPC拦截器可以统一处理请求前后的逻辑，比如日志记录、身份验证、错误处理等。gRPC本身不直接提供中间件机制，但通过拦截器（Interceptor）可以实现类似功能。拦截器分为客户端拦截器和服务端拦截器，下面重点介绍服务端如何使用拦截器处理请求。

什么是gRPC拦截器

拦截器本质上是一个函数，在gRPC方法执行前后插入自定义逻辑。服务端拦截器可以在每个RPC调用开始前进行权限校验、日志打印、超时控制等操作。

编写服务端拦截器

服务端拦截器的类型是 grpc.UnaryServerInterceptor，其函数签名如下：

你可以按需实现该函数。例如，实现一个简单的日志和错误恢复拦截器：

func loggingInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
    // 请求前
    log.Printf("Received %s", info.FullMethod)
    
    // 执行实际的handler
    resp, err := handler(ctx, req)
    
    // 请求后
    if err != nil {
        log.Printf("Error calling %s: %v", info.FullMethod, err)
    } else {
        log.Printf("Successfully called %s", info.FullMethod)
    }
    
    return resp, err
}

注册拦截器到gRPC服务器

使用 grpc.UnaryInterceptor 选项将拦截器注册到gRPC服务器：

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

如果你有多个拦截器，可以使用第三方库如 github.com/grpc-ecosystem/go-grpc-middleware 来链式组合：

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

s := grpc.NewServer(grpc.UnaryInterceptor(
    grpc_middleware.ChainUnaryServer(
        loggingInterceptor,
        authInterceptor,  // 例如鉴权拦截器
        recoveryInterceptor,
    ),
))

常见使用场景

• 身份验证：在拦截器中解析Token并验证用户身份，失败则返回错误。
• 日志记录：记录每次调用的方法名、参数、耗时等信息。
• 错误恢复：通过 defer + recover 防止panic导致服务崩溃。
• 限流与监控：结合Prometheus等工具统计QPS或延迟。

基本上就这些。拦截器让gRPC服务具备了更强的可维护性和可观测性，合理使用能大幅减少重复代码。注意拦截器只对 unary 调用生效，如果使用 streaming，还需实现 stream interceptor。不过大多数场景下 unary 拦截器已足够。

今天带大家了解了的相关知识，希望对你有所帮助；关于Golang的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~