gin 本身不处理 grpc 客户端调用，所谓“集成”实为在 grpc.dial() 阶段注册 unaryclientinterceptor，gin 仅作为调用方；其中间件对 grpc 底层 tcp 调用完全不可见，context、metadata 等需显式透传。
直接说结论：Gin 本身不处理 gRPC 客户端调用，所谓“Gin 集成 gRPC 客户端拦截中间件”，本质是把 gRPC 的 UnaryClientInterceptor 注册到 gRPC 连接上，再让 Gin 的 handler 调用这个已配置拦截器的 client —— 拦截逻辑完全在 gRPC 层，Gin 只是调用方。
为什么不能在 Gin 中间件里拦截 gRPC 客户端请求
Gin 中间件（如 gin.HandlerFunc）只作用于 HTTP 请求生命周期，对 grpc.ClientConn 发起的底层 TCP 调用完全不可见。你在 Gin 的 Use() 里加日志或鉴权逻辑，不会触发任何 gRPC 请求前/后的钩子。
- gRPC 客户端调用绕过 Gin 的路由、中间件、context 传递链
- Gin 的
c.Request.Context()和 gRPC 的ctx context.Context是两个独立上下文，不自动透传 - 试图在 Gin 中间件里手动注入 metadata 或修改 req 结构，属于重复造轮子且极易出错
正确注册 gRPC 客户端拦截器的写法
必须通过 grpc.WithUnaryInterceptor（或 grpc.WithChainUnaryInterceptor）在 grpc.Dial() 阶段注册，且拦截器函数签名必须严格匹配 grpc.UnaryClientInterceptor：
func authInterceptor(token string) grpc.UnaryClientInterceptor {
return func(ctx context.Context, method string, req, reply interface{}, cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error {
// 注入 Authorization header
md := metadata.Pairs("Authorization", "Bearer "+token)
ctx = metadata.NewOutgoingContext(ctx, md)
return invoker(ctx, method, req, reply, cc, opts...)
}
}
conn, err := grpc.Dial(
"user-srv:50051",
grpc.WithInsecure(),
grpc.WithUnaryInterceptor(authInterceptor("xxx-token")),
)
if err != nil {
log.Fatal(err)
}
client := pb.NewUserServiceClient(conn)
- 拦截器必须返回
error，不能忽略invoker()调用，否则 RPC 不会真正发出 - 若需多个拦截器（如日志 + 认证 + 重试），优先用
grpc-middleware的grpc.WithChainUnaryInterceptor()，避免手动嵌套 - token 不建议硬编码，应从 Gin 的
c.Get("user_token")或全局配置中动态获取并传入闭包
Gin Handler 中安全使用带拦截器的 gRPC client
Gin handler 里调用 gRPC client 时，唯一需要关注的是 context 传递和错误处理，而非“再加一层拦截”：
func GetUserHandler(c *gin.Context) {
userID := c.Param("id")
// 从 Gin context 提取必要信息（如 traceID、token）
token, _ := c.Get("auth_token")
ctx := c.Request.Context() // 复用 Gin 的 cancelable context
// 构造 gRPC 请求
req := &pb.GetUserRequest{Id: userID}
resp, err := client.GetUser(ctx, req)
if err != nil {
c.JSON(http.StatusServiceUnavailable, gin.H{"error": err.Error()})
return
}
c.JSON(http.StatusOK, resp)
}
- 务必把
c.Request.Context()传给 gRPC 方法，否则超时、取消信号无法生效 - 不要在 handler 里重新创建
grpc.ClientConn，应作为全局变量或依赖注入初始化一次 - 如果 gRPC server 返回了
status.Error()，err已包含详细码（如codes.Unauthenticated），可据此映射 HTTP 状态码
容易被忽略的坑：metadata 透传与跨服务 traceID
当 Gin 作为 API 网关调用多个 gRPC 服务时，若需链路追踪，必须显式从 HTTP header 提取 trace-id 并注入 gRPC metadata，否则 span 会断裂：
- Gin 中读取：
traceID := c.GetHeader("X-Trace-ID") - 在拦截器中注入：
md := metadata.Pairs("X-Trace-ID", traceID) - 注意：gRPC metadata key 默认小写，但部分链路系统（如 Jaeger）要求首字母大写，需确认后端接收规则
- 若使用
grpc.WithBlock()初始化连接，可能导致 Gin handler 阻塞，生产环境应禁用或设合理grpc.WithTimeout()
