Kratos中间件必须通过http.Middleware或grpc.Middleware显式传入ServerOption才生效,否则静默失效;HTTP/gRPC中间件不可混用,且需严格匹配middleware.Middleware签名,ctx.Value()需显式透传。

中间件必须通过 http.Middleware 或 grpc.Middleware 显式传入 ServerOption,否则完全不生效。 Kratos 不会自动扫描或注入中间件,漏掉这一步是线上服务静默丢失日志、鉴权、限流能力的最常见原因。
中间件必须用 ServerOption 注册到 http.Server 或 grpc.Server
Kratos 的中间件不是“挂载”在路由上,而是绑定在整个 HTTP/gRPC 服务器实例生命周期里。你写好了 jwt.Server() 或 ratelimit.Server(),但没放进 http.NewServer() 的 opts 列表,它就永远不会执行。
- 错误写法:
http.NewServer(http.Address(":8000"))—— 中间件参数直接缺失 - 正确写法:
http.NewServer(http.Address(":8000"), http.Middleware(m1, m2, m3)) - 多个中间件按从右到左顺序执行(即
m3 → m2 → m1 → handler),和 Go 原生 Chain 行为一致 - HTTP 和 gRPC 中间件不能混用:
jwt.Server()是 HTTP 专用;jwt.GRPCServer()才用于 gRPC 传输层
ctx.Value() 在中间件链中丢失的典型原因
你在前置中间件里用 ctx = context.WithValue(ctx, key, val) 塞了数据,但后续中间件或业务 handler 拿不到——这不是 Kratos bug,而是 net/http 默认不透传 context 变更。
- HTTP 中间件接收的是
*http.Request,必须显式调用r = r.WithContext(ctx)再传给next.ServeHTTP() - 别依赖
transport.HTTPContext():它返回的是空 context,不是 request 关联的 context - 要用
transport.HTTPRequestContext(r)获取带 transport 信息的 context,再基于它做WithValue - 如果用了 Kratos 的
http.Request封装(如http.RequestFromContext()),也要确保原始 request 已被更新
自定义中间件必须返回标准 Middleware 类型
自己写的中间件函数签名必须严格匹配 Kratos 定义的 middleware.Middleware 类型,否则编译报错或运行时 panic。
- 正确签名:
func(myMiddleware middleware.Middleware) middleware.Middleware - 常见错误:写成
func(http.Handler) http.Handler—— 这是原生 net/http 的类型,Kratos 的http.Middleware接收的是middleware.Handler,二者不兼容 - 务必 import
github.com/go-kratos/kratos/v2/middleware,而不是net/http - 示例骨架:
func MyAuth(logger log.Logger) middleware.Middleware { return func(handler middleware.Handler) middleware.Handler { return func(ctx context.Context, req any) (any, error) { // 前置逻辑 reply, err := handler(ctx, req) // 后置逻辑 return reply, err } } }
最容易被忽略的一点:Kratos 中间件的 req 参数是任意类型(any),它可能是 *http.Request、*grpc.RequestInfo 或业务 proto 结构体,取决于传输层。不要在中间件里硬转 *http.Request,除非你确定只跑 HTTP;需要统一取路径或方法名,应通过 transport.FromContext(ctx) 提取 transport 信息。


















