177 lines
6.2 KiB
Markdown
177 lines
6.2 KiB
Markdown
---
|
||
tags: [grpc, interceptor, middleware, context-propagation, metadata]
|
||
create time: 2026-05-07 16:00
|
||
---
|
||
|
||
# Interceptor 与上下文传播
|
||
|
||
## 概述
|
||
|
||
Interceptor 是 gRPC 的切面编程能力，相当于 Web 框架中的 Middleware。每个 RPC 调用都会经过 **Unary Interceptor** 或 **Stream Interceptor** 链——无论它是普通的一问一答还是长时间的双向流。
|
||
|
||
本文涵盖拦截器的编写模式、链式串联技巧，以及最重要的**上下文传播**机制。
|
||
|
||
## Interceptor 链架构
|
||
|
||
```mermaid
|
||
graph LR
|
||
subgraph ClientChain["客户端拦截器链"]
|
||
CAuth["认证拦截"] --> CMetric["指标采集"] --> CRetry["重试策略"] --> CHand["RPC 调用"]
|
||
end
|
||
|
||
subgraph ServerChain["服务端拦截器链"]
|
||
SHand["RPC Handler"] --> SMetric["指标采集"] --> SLog["日志记录"] --> SAuth["鉴权拦截"]
|
||
end
|
||
|
||
CHand ==>|HTTP/2| SHand
|
||
|
||
style CAuth fill:#fce4ec
|
||
style SAuth fill:#e3f2fd
|
||
```
|
||
|
||
### 典型执行顺序
|
||
|
||
| 位置 | 拦截器 | 职责 |
|
||
|------|--------|------|
|
||
| 客户端 | Metrics | 记录请求耗时、成功/失败计数 |
|
||
| 客户端 | Retry | 根据错误码决定是否自动重试 |
|
||
| 客户端 | Auth | 注入 Token / mTLS 证书 |
|
||
| 服务端 | Auth | 验证 Token 有效性 |
|
||
| 服务端 | Logging | 记录完整的请求/响应元信息 |
|
||
| 服务端 | Metrics | 统计服务端处理时间 |
|
||
| 服务端 | Handler | 实际业务逻辑 |
|
||
|
||
> [!warning] Go 中拦截器注册的陷阱
|
||
>
|
||
> Go 的 `grpc.WithUnaryInterceptor` 会**覆盖**而非追加。如果注册多次，只有最后一次生效。所以要用一个统一的包装函数串联所有逻辑：
|
||
|
||
## 链式包装函数
|
||
|
||
```go
|
||
func chainUnaryInterceptors(interceptors ...grpc.UnaryServerInterceptor) grpc.UnaryServerInterceptor {
|
||
n := len(interceptors)
|
||
return func(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) {
|
||
ch := handler
|
||
for i := n - 1; i >= 0; i-- {
|
||
ih := ch
|
||
ch = func(c context.Context, r any) (any, error) {
|
||
return interceptors[i](c, r, info, ih)
|
||
}
|
||
}
|
||
return ch(ctx, req)
|
||
}
|
||
}
|
||
```
|
||
|
||
调用方只需传入所有拦截器即可：
|
||
|
||
```go
|
||
allInterceptors := []grpc.UnaryServerInterceptor{
|
||
TraceInterceptor(),
|
||
AuthInterceptor(),
|
||
LoggingInterceptor(),
|
||
MetricsInterceptor(),
|
||
}
|
||
|
||
server := grpc.NewServer(
|
||
grpc.UnaryInterceptor(chainUnaryInterceptors(allInterceptors...)),
|
||
grpc.StreamInterceptor(chainStreamInterceptors(...)),
|
||
)
|
||
```
|
||
|
||
> [!tip] 其他语言的差异
|
||
>
|
||
> - **Go**：需要通过上述手动链式包装，因为 `NewServer` 只接受一个拦截器
|
||
> - **Java**：`Server.intercept()` 支持注册多个拦截器，按注册顺序依次执行
|
||
> - **Node.js**：通过插件体系 `Server.addServiceDefinition` 间接实现
|
||
|
||
## 实战：统一鉴权拦截器
|
||
|
||
```go
|
||
// auth interceptor
|
||
func AuthInterceptor() grpc.UnaryServerInterceptor {
|
||
return func(ctx context.Context, req any,
|
||
info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) {
|
||
|
||
// 白名单路径跳过鉴权
|
||
skipPaths := []string{"/health.Health/Check", "/grpc.reflection.v1.ServerReflection/ServerReflectionInfo"}
|
||
for _, p := range skipPaths {
|
||
if info.FullMethod == p {
|
||
return handler(ctx, req)
|
||
}
|
||
}
|
||
|
||
// 从 metadata 中提取 Token
|
||
md, ok := metadata.FromIncomingContext(ctx)
|
||
if !ok {
|
||
return nil, status.Error(codes.Unauthenticated, "missing metadata")
|
||
}
|
||
|
||
tokens := md.Get("authorization")
|
||
if len(tokens) == 0 || !validateToken(tokens[0]) {
|
||
return nil, status.Error(codes.Unauthenticated, "invalid token")
|
||
}
|
||
|
||
// 将用户信息注入 ctx（传递给下游 handler）
|
||
userCtx := context.WithValue(ctx, "userID", extractUserID(tokens[0]))
|
||
return handler(userCtx, req)
|
||
}
|
||
}
|
||
```
|
||
|
||
## 上下文传播 (Context Propagation)
|
||
|
||
gRPC 天然支持通过 `metadata` 传递自定义元数据——这是实现分布式追踪、链路溯源的核心机制。
|
||
|
||
### 手动传播
|
||
|
||
```go
|
||
// 服务端注入 trace ID
|
||
ctx = metadata.AppendToOutgoingContext(ctx,
|
||
"x-trace-id", traceID,
|
||
"x-user-id", userID,
|
||
)
|
||
|
||
// 客户端接收
|
||
md, ok := metadata.FromOutgoingContext(ctx)
|
||
traceID := md.Get("x-trace-id")
|
||
```
|
||
|
||
### OpenTelemetry 自动传播
|
||
|
||
手动维护 metadata 繁琐且易遗漏。使用 `otelgrpc` 中间件可以自动注入 W3C Trace Context：
|
||
|
||
```go
|
||
import "go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"
|
||
|
||
server := grpc.NewServer(
|
||
grpc.StatsHandler(otelgrpc.NewServerStatsHandler()),
|
||
// otelgrpc 自动在 metadata 中注入 traceparent / tracestate
|
||
)
|
||
|
||
conn, _ := grpc.Dial(target,
|
||
grpc.WithStatsHandler(otelgrpc.NewClientStatsHandler()),
|
||
)
|
||
```
|
||
|
||
> [!keypoint] 为什么需要上下文传播
|
||
>
|
||
> 当一个请求穿越 5 个微服务时，如果没有上下文传播，你在日志系统中看到的是 5 条孤立的记录。有了 W3C Trace Context，每层服务自动将 `traceparent` 透传给下一跳——最终汇聚成一条完整的调用链路，这就是 [[02-服务治理/03-分布式追踪]] 的核心能力。
|
||
|
||
## 拦截器最佳实践
|
||
|
||
> [!summary] 五条黄金法则
|
||
>
|
||
> 1. **不要吞掉错误**——拦截器应该记录错误再转发给下一个，而不是独自决定忽略
|
||
> 2. **不要在拦截器里做重型计算**——它处于热路径，每条 RPC 都要经过
|
||
> 3. **设置合理的超时**——拦截器里的 `context.WithTimeout` 不应短于原始请求的 deadline
|
||
> 4. **白名单排除健康检查**——`/health.Health/Check` 和 reflection 服务不需要鉴权和日志
|
||
> 5. **用 `info.FullMethod` 做条件判断**——格式为 `/package.Service/Method`，如 `/order.v1.OrderService/CreateOrder`
|
||
|
||
## 关联笔记
|
||
|
||
- [[01-协议与架构]] — 拦截器位于 gRPC Framework 层，在 HTTP/2 之前处理请求
|
||
- [[05-错误处理]] — 拦截器经常需要根据错误码决定重试或降级策略
|
||
- [[02-服务治理/03-分布式追踪]] — Context 传播是实现分布式追踪的前提
|
||
- [[02-服务治理/02-安全机制]] — 鉴权拦截器是安全机制在代码层的落地形式
|