4. gRPC 拦截器(Interceptor)原理：客户端拦截器与服务端拦截器、拦截器生命周期、UnaryInterceptor与StreamInterceptor

4.1 拦截器核心概念

gRPC 拦截器（Interceptor）是 gRPC 框架提供的一种 中间件机制，允许开发者在 RPC 调用链中插入自定义逻辑，而无需修改业务代码。拦截器在微服务安全架构中扮演着 安全网关 的角色，是权限验证、日志记录、请求追踪、限流熔断等横切关注点的理想实现位置。

4.2 客户端拦截器与服务端拦截器

gRPC 拦截器分为两大类：客户端拦截器 和 服务端拦截器。两者在调用链中的位置和职责不同，但遵循相同的设计哲学。

4.3 拦截器生命周期

理解拦截器的生命周期对于正确实现权限验证至关重要。拦截器在 gRPC 调用链中形成一个 洋葱模型，每一层拦截器包裹着下一层，最终到达业务处理逻辑。

4.4 UnaryInterceptor 与 StreamInterceptor

gRPC 支持两种 RPC 模式：一元 RPC（Unary RPC） 和 流式 RPC（Streaming RPC）。针对这两种模式，gRPC 提供了对应的拦截器接口。

4.4.1 UnaryInterceptor（一元拦截器）

一元拦截器处理 一次请求 + 一次响应 的 RPC 调用。在权限验证场景中，一元拦截器是最常用的拦截器类型，适用于登录验证、资源查询等标准请求-响应模式。

// 服务端一元拦截器签名
func UnaryServerInterceptor(
    ctx context.Context,
    req interface{},
    info *grpc.UnaryServerInfo,
    handler grpc.UnaryHandler,
) (interface{}, error) {
    // 前置处理：权限验证
    if err := authenticate(ctx); err != nil {
        return nil, err
    }
    // 调用业务方法
    resp, err := handler(ctx, req)
    // 后置处理：审计日志
    logAccess(ctx, info, err)
    return resp, err
}

// 客户端一元拦截器签名
func UnaryClientInterceptor(
    ctx context.Context,
    method string,
    req, reply interface{},
    cc *grpc.ClientConn,
    invoker grpc.UnaryInvoker,
    opts ...grpc.CallOption,
) error {
    // 前置处理：注入 Token
    ctx = attachToken(ctx)
    // 发起 RPC 调用
    err := invoker(ctx, method, req, reply, cc, opts...)
    // 后置处理：错误处理
    return err
}

4.4.2 StreamInterceptor（流式拦截器）

流式拦截器处理 持续的数据流，包括服务端流、客户端流和双向流。流式拦截器的生命周期更长，需要在流的整个生命周期内维护上下文状态。

// 服务端流式拦截器签名
func StreamServerInterceptor(
    srv interface{},
    ss grpc.ServerStream,
    info *grpc.StreamServerInfo,
    handler grpc.StreamHandler,
) error {
    // 前置处理：验证流建立权限
    if err := authorizeStream(ss.Context(), info); err != nil {
        return err
    }
    // 包装流对象，拦截每条消息
    wrappedStream := &authServerStream{ss}
    // 处理流
    return handler(srv, wrappedStream)
}

// 客户端流式拦截器签名
func StreamClientInterceptor(
    ctx context.Context,
    desc *grpc.StreamDesc,
    cc *grpc.ClientConn,
    method string,
    streamer grpc.Streamer,
    opts ...grpc.CallOption,
) (grpc.ClientStream, error) {
    // 前置处理：注入流级别凭证
    ctx = attachStreamCredentials(ctx)
    // 创建流
    clientStream, err := streamer(ctx, desc, cc, method, opts...)
    // 包装流对象
    return &authClientStream{clientStream}, err
}

4.5 拦截器类型对比

4.6 拦截器链与执行顺序

当注册多个拦截器时，gRPC 按照 先进先出（FIFO） 的顺序执行前置逻辑，按照 后进先出（LIFO） 的顺序执行后置逻辑。这种链式结构非常适合构建多层安全防护。

4.7 拦截器在权限验证中的最佳实践

• 分层验证： 使用多个拦截器实现分层安全策略。例如：日志拦截器（A）→ 认证拦截器（B）→ 授权拦截器（C）→ 业务方法。
• 短路机制： 在认证或授权失败时，拦截器应直接返回错误，不再调用后续 handler，实现快速失败。
• 上下文传递： 使用 context.WithValue() 在拦截器之间传递认证结果（如用户 ID、角色信息），避免重复解析 Token。
• 流式安全： 对于流式 RPC，在 StreamServerInterceptor 中包装 grpc.ServerStream，重写 RecvMsg() 和 SendMsg() 方法，实现消息级别的权限校验。
• 性能考量： 一元拦截器性能开销极低，适合高频调用；流式拦截器需注意每条消息的验证开销，建议使用缓存或预计算优化。