gRPC拦截器可用于在请求处理前后执行通用逻辑，如日志、认证、错误处理等。服务端拦截器通过grpc.UnaryInterceptor注册，用于权限校验和日志记录；客户端拦截器通过grpc.WithUnaryInterceptor添加，可自动注入token或监控耗时。使用grpc-middleware可链式组合多个拦截器。常见应用场景包括身份认证、日志监控、错误统一处理、限流熔断及上下文传递。流式拦截器支持流接口的拦截，适用于连接级控制。拦截器应保持轻量，避免阻塞操作。合理使用拦截器可提升代码清晰度与系统健壮性。
在使用 Golang 开发 gRPC 服务时，拦截器（Interceptor）是一种非常实用的机制，能够帮助我们在请求真正进入业务逻辑前或响应返回前统一处理一些通用操作，比如日志记录、身份验证、错误处理、限流等。gRPC 本身不直接提供拦截器功能，但通过 grpc-go 社区实现，支持在客户端和服务端注册拦截器。
一、服务端拦截器：统一处理入站请求
服务端拦截器用于在 gRPC 方法执行前拦截请求，适合做权限校验、日志打印、监控统计等。
定义一个服务端 unary 拦截器函数，其类型为：
func(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (resp interface{}, err error)示例：实现一个简单的日志和错误恢复拦截器：
立即学习“go语言免费学习笔记（深入）”；
func loggingInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
// 请求前
log.Printf("Received request: %s", info.FullMethod)
// 执行实际 handler
resp, err := handler(ctx, req)
// 响应后
if err != nil {
log.Printf("Error handling request: %v", err)
} else {
log.Printf("Request processed successfully")
}
return resp, err
}
注册到 gRPC 服务端：
s := grpc.NewServer(
grpc.UnaryInterceptor(loggingInterceptor),
)
如果需要多个拦截器，可以使用 grpc-middleware 库组合：
import "github.com/grpc-ecosystem/go-grpc-middleware"
s := grpc.NewServer(
grpc.UnaryInterceptor(grpc_middleware.ChainUnaryServer(
loggingInterceptor,
authInterceptor,
recoveryInterceptor,
)),
)
二、客户端拦截器：统一处理出站请求
客户端拦截器用于在调用远程方法前添加公共逻辑，如自动注入认证 token、监控调用耗时等。
客户端 unary 拦截器函数签名：
func(ctx context.Context, method string, req, reply interface{}, cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error
示例：添加 JWT token 到 metadata：
func authInterceptor(ctx context.Context, method string, req, reply interface{}, cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error {
ctx = metadata.AppendToOutgoingContext(ctx, "authorization", "Bearer your-jwt-token")
return invoker(ctx, method, req, reply, cc, opts...)
}
创建客户端连接时启用：
conn, err := grpc.Dial(
"localhost:50051",
grpc.WithInsecure(),
grpc.WithUnaryInterceptor(authInterceptor),
)
多个拦截器也可通过 ChainUnaryClient 组合：
grpc.Dial(
"localhost:50051",
grpc.WithInsecure(),
grpc.WithUnaryInterceptor(grpc_middleware.ChainUnaryClient(
authInterceptor,
loggingClientInterceptor,
retryInterceptor,
)),
)
三、常见应用场景与最佳实践
- 身份认证：在拦截器中解析 metadata 中的 token，验证用户合法性，并将用户信息存入 Context 供后续使用。
- 日志与监控：记录请求方法、耗时、错误码，便于排查问题和性能分析。
- 错误统一处理：将内部 panic 捕获并转换为标准 gRPC 错误码（如 Internal、Unauthenticated）。
- 限流与熔断：结合中间件如 Sentinel 或自定义计数器，在拦截器中实现简单限流逻辑。
- 上下文传递：在分布式系统中，通过拦截器透传 trace_id、user_id 等上下文信息。
注意：拦截器中尽量避免阻塞操作，保持轻量，以免影响整体性能。
四、流式拦截器（Streaming Interceptor）
对于 gRPC 的流式接口（stream），也有对应的流拦截器，分为客户端流和服务器流拦截器。例如服务端流拦截器：
func streamInterceptor(srv interface{}, ss grpc.ServerStream, info *grpc.StreamServerInfo, handler grpc.StreamHandler) error {
log.Printf("Stream request: %s", info.FullMethod)
return handler(srv, ss)
}
注册方式类似：
s := grpc.NewServer(
grpc.StreamInterceptor(streamInterceptor),
)
流式场景下可用来控制连接生命周期、做连接级别的认证等。
基本上就这些。合理使用 gRPC 拦截器，能让代码更清晰、职责更分明，把横切关注点从业务逻辑中剥离出来，是构建健壮微服务的重要手段。
