Go gRPC 拦截器链：日志、Trace、重试和限流不要搅在一起

Go gRPC 拦截器链：日志、Trace、重试和限流不要搅在一起

一、一个 UnaryInterceptor 塞进四个职责：这是拦截器，不是垃圾桶

gRPC 的拦截器（Interceptor）机制是 Go 生态中最优雅的中间件模式之一。服务端拦截器的签名清晰明了：func(ctx context.Context, req interface{}, info *UnaryServerInfo, handler UnaryHandler) (interface{}, error)。开发者可以在 handler 调用前后注入任意逻辑。

在实践中，很多团队的做法是把所有横切关注点塞进一个巨大的拦截器。日志打印、Trace span 创建、重试逻辑、限流判断、参数校验——全部写在一个 500 行的 ServerInterceptor 函数里。乍看起来能跑，但隐患在第一次线上排查时就会暴露。

假设一个请求触发了限流被拒绝。在巨型拦截器中，限流判断在第 30 行，日志打印在第 25 行。排查人员看到的日志是"请求已接收"，但实际上请求已经被拒绝。一个请求有四种不同的生命周期阶段（拦截前、拦截通过、处理中、处理完成），四种状态应该对应四条独立的日志——而不是一条说不清道不明的混杂日志。

基础设施不需要漂亮话。拦截器的职责应该是单一、可组合、可独立测试的。编排拦截器的方式决定了线上排障的效率。

二、拦截器链的执行模型与组合模式

gRPC 的拦截器链本质上是一个洋葱模型：请求从最外层的拦截器进入，逐层向内传递到 handler，响应再从内到外逐层返回。当只有一个巨型拦截器时，洋葱变成一个实心球——无法独立控制每一层的行为。

sequenceDiagram
    participant Client as gRPC 客户端
    participant Trace as Trace 拦截器
    participant RateLimit as 限流拦截器
    participant Retry as 重试拦截器
    participant Logging as 日志拦截器
    participant Handler as 业务 Handler
    
    Client->>Trace: 1. 创建 Span
    Trace->>RateLimit: 2. 检查配额
    alt 配额不足
        RateLimit-->>Trace: RESOURCE_EXHAUSTED
        Trace->>Trace: 记录 Span 状态
        Trace-->>Client: 返回限流错误
    else 配额充足
        RateLimit->>Retry: 3. 记录重试上下文
        Retry->>Logging: 4. 记录请求元数据
        Logging->>Handler: 5. 执行业务逻辑
        Handler-->>Logging: 返回响应
        Logging->>Logging: 记录响应耗时
        Logging-->>Retry: 传递响应
        Retry->>Retry: 检查是否需要重试
        Retry-->>RateLimit: 传递响应
        RateLimit->>RateLimit: 释放配额
        RateLimit-->>Trace: 传递响应
        Trace->>Trace: 记录 Span 结束
        Trace-->>Client: 返回最终响应
    end

关键设计原则：

• 拦截器顺序决定了行为语义。限流应在外层（早期拒绝，避免浪费下游资源），Trace 应在最外层（包裹整个请求生命周期），重试在内层（只重试 handler 执行，不重试拦截逻辑）。
• 每个拦截器只做一件事。日志拦截器不关心 Trace ID，它只从 context 中提取；限流拦截器不关心请求内容，它只看配额。
• 错误传递必须遵循 gRPC status 约定。不用自定义 error 类型跨拦截器传递，使用 status.Errorf(codes.Code, "msg")。

三、可组合拦截器链的生产实践

3.1 独立拦截器实现

package interceptors

import (
	"context"
	"strings"
	"time"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/trace"
	"golang.org/x/time/rate"
	"google.golang.org/grpc"
	"google.golang.org/grpc/codes"
	"google.golang.org/grpc/metadata"
	"google.golang.org/grpc/status"
)

// ============================================
// 1. Trace 拦截器：创建 Span，传播 Trace Context
// ============================================
func UnaryServerTraceInterceptor() grpc.UnaryServerInterceptor {
	tracer := otel.Tracer("grpc-server")

	return func(ctx context.Context, req interface{},
		info *grpc.UnaryServerInfo, handler grpc.UnaryHandler,
	) (interface{}, error) {
		// 从 gRPC metadata 提取上游 trace context，建立父子 Span 关系。
		md, ok := metadata.FromIncomingContext(ctx)
		if ok {
			ctx = otel.GetTextMapPropagator().Extract(ctx,
				metadataReaderWriter{md})
		}

		ctx, span := tracer.Start(ctx, info.FullMethod,
			trace.WithAttributes(
				attribute.String("rpc.method", info.FullMethod),
			),
		)
		defer span.End()

		resp, err := handler(ctx, req)
		if err != nil {
			span.RecordError(err)
			// 从 gRPC status 提取错误码，写入 Span。
			if st, ok := status.FromError(err); ok {
				span.SetAttributes(
					attribute.String("rpc.grpc.status_code", st.Code().String()),
				)
			}
		}
		return resp, err
	}
}

// ============================================
// 2. 限流拦截器：每个方法独立的速率限制
// ============================================
type RateLimiter struct {
	// 使用令牌桶算法：每秒允许 burst 个请求，稳态 rate 个请求/秒。
	limiters map[string]*rate.Limiter
}

func NewRateLimiter(config map[string]struct{ Rate, Burst int }) *RateLimiter {
	limiters := make(map[string]*rate.Limiter)
	for method, cfg := range config {
		limiters[method] = rate.NewLimiter(rate.Limit(cfg.Rate), cfg.Burst)
	}
	return &RateLimiter{limiters: limiters}
}

func (rl *RateLimiter) UnaryServerInterceptor() grpc.UnaryServerInterceptor {
	return func(ctx context.Context, req interface{},
		info *grpc.UnaryServerInfo, handler grpc.UnaryHandler,
	) (interface{}, error) {
		limiter, ok := rl.limiters[info.FullMethod]
		if !ok {
			// 未配置限流的方法直接放行。
			return handler(ctx, req)
		}
		if !limiter.Allow() {
			return nil, status.Errorf(codes.ResourceExhausted,
				"rate limit exceeded for %s", info.FullMethod)
		}
		return handler(ctx, req)
	}
}

// ============================================
// 3. 重试拦截器：仅对幂等方法生效
// ============================================
var retriableCodes = map[codes.Code]bool{
	codes.Unavailable:    true,
	codes.DeadlineExceeded: true,
	codes.ResourceExhausted: true,
}

func UnaryServerRetryInterceptor(maxRetries int, baseDelay time.Duration) grpc.UnaryServerInterceptor {
	return func(ctx context.Context, req interface{},
		info *grpc.UnaryServerInfo, handler grpc.UnaryHandler,
	) (interface{}, error) {
		// 服务端重试仅适用于幂等操作。非幂等方法的重试应放在客户端拦截器中。
		// 此处通过 gRPC method 的后缀判断是否为只读方法（约定优于配置）。
		if !isIdempotent(info.FullMethod) {
			return handler(ctx, req)
		}

		var lastErr error
		for attempt := 0; attempt <= maxRetries; attempt++ {
			if attempt > 0 {
				delay := baseDelay * time.Duration(1<<(attempt-1))
				select {
				case <-ctx.Done():
					return nil, ctx.Err()
				case <-time.After(delay):
				}
			}
			resp, err := handler(ctx, req)
			if err == nil {
				return resp, nil
			}
			st, ok := status.FromError(err)
			if !ok || !retriableCodes[st.Code()] {
				return nil, err
			}
			lastErr = err
		}
		return nil, lastErr
	}
}

func isIdempotent(method string) bool {
	// 约定：以 List/Get/Query/Search 结尾的方法是只读幂等的。
	for _, suffix := range []string{"List", "Get", "Query", "Search", "Lookup"} {
		if strings.HasSuffix(method, suffix) {
			return true
		}
	}
	return false
}

// ============================================
// 4. 日志拦截器：结构化请求日志
// ============================================
func UnaryServerLoggingInterceptor() grpc.UnaryServerInterceptor {
	return func(ctx context.Context, req interface{},
		info *grpc.UnaryServerInfo, handler grpc.UnaryHandler,
	) (interface{}, error) {
		start := time.Now()
		resp, err := handler(ctx, req)
		latency := time.Since(start)

		code := codes.OK
		if err != nil {
			if st, ok := status.FromError(err); ok {
				code = st.Code()
			} else {
				code = codes.Internal
			}
		}

		// 通过结构化日志库输出，携带 traceID 和 spanID 以便关联。
		// 日志字段由 logging 框架统一管理，不在拦截器中写死格式。
		_ = latency
		_ = code
		// slog.LogAttrs(ctx, slog.LevelInfo, "grpc request",
		// 	slog.String("method", info.FullMethod),
		// 	slog.String("code", code.String()),
		// 	slog.Duration("latency", latency),
		// )
		return resp, err
	}
}
// ============================================
// 5. 拦截器链编排：通过 grpc.ChainUnaryInterceptor 组装
// ============================================
func main() {
	rateLimiter := NewRateLimiter(map[string]struct{ Rate, Burst int }{
		"/inference.v1.LLMInference/Generate": {Rate: 50, Burst: 100},
	})

	server := grpc.NewServer(
		grpc.ChainUnaryInterceptor(
			// 最外层：Trace（包裹全部）
			UnaryServerTraceInterceptor(),
			// 第二层：限流（早期拒绝）
			rateLimiter.UnaryServerInterceptor(),
			// 第三层：日志（记录所有通过的请求）
			UnaryServerLoggingInterceptor(),
			// 最内层：重试（仅重试 handler 执行）
			UnaryServerRetryInterceptor(3, 50*time.Millisecond),
		),
	)
	_ = server
}

几个关键编排决策：

• Trace 在最外层：确保 Span 的 end 方法在响应离开服务端之前被调用。如果 Trace 在内层，外层拦截器产生的错误不会被记录到 Span 中。
• 重试在最内层：重试只应用于 handler 的执行。如果重试在外层，每次重试都会重复执行限流检查、日志记录和 Trace span 创建，产生大量噪音。
• 限流在 Trace 之后、日志之前：被拒绝的请求仍在 Trace 中（可以看到被限流的次数），但在日志中不产生"成功处理"的记录。

四、拦截器链的维护陷阱

拦截器顺序的隐式依赖。当 team 成员在不同时间添加拦截器时，很容易忽略顺序的语义。例如有人在 Trace 拦截器内部使用了 metadata.FromIncomingContext(ctx)，但随后有人添加了一个"参数校验拦截器"并放在了 Trace 之前——结果 Trace 拦截器读取不到 metadata，因为参数校验拦截器修改了 context 但没有传递 metadata。解决方案：拦截器链的顺序必须在团队文档中明确记录，并在 code review 中强制检查。

拦截器中的 goroutine 泄漏。如果拦截器中启动了 goroutine 处理异步逻辑（如缓存预热），必须确保 goroutine 在请求结束时能被正确取消。依赖 ctx.Done() 是首选方式，但注意外层拦截器的 context，如 Trace 拦截器创建的 context 可能在 handler 返回后就被 cancel，内层拦截器的 goroutine 会收到 cancel 信号。

性能开销。每个拦截器都是一次函数调用。在 QPS 数十万的场景中，拦截器过多可能导致栈深度过大。Go 的调用栈默认 1GB，通常不是瓶颈，但 pprof 的 flame graph 会显示调用层次过深。保持拦截器数量在 5 个以内，并将纯计算逻辑（如限流）实现为无锁或低锁设计。

五、总结

gRPC 拦截器链不应该是一个巨大的垃圾桶，而应该是一组职责单一、按序排列的独立组件。核心实践：

1. 按语义分层：Trace（最外）→ 限流 → 日志 → 业务特定校验 → 重试（最内）。顺序不可随意调换。

2. 每个拦截器只做一件事。如果一个拦截器在"顺便"做另一件事——拆出来。

3. 使用 grpc.ChainUnaryInterceptor 显式声明顺序。不要使用多个 grpc.UnaryInterceptor 参数（它们以注册的逆序执行，容易出错）。

4. 服务端重试仅限幂等方法。非幂等操作的重试逻辑放在客户端拦截器。

编排良好的拦截器链在排查线上问题时，每一步都有清晰的轨迹。编排混乱的拦截器链只会让问题更深地隐藏在一个 500 行的函数里。