Kratos中间件必须实现middleware.Middleware接口,即func(next middleware.Handler) middleware.Handler,而非原生func(http.Handler) http.Handler;其Handler签名是func(ctx context.Context, req any) (any, error),需用transport.FromContext(ctx)获取元信息,执行顺序为从右往左嵌套。

中间件必须实现 middleware.Middleware 接口,不是 func(http.Handler) http.Handler
Kratos 的中间件和 net/http 原生中间件不兼容。直接传入 func(http.Handler) http.Handler 会导致 panic,因为 Kratos 的 http.Server 内部根本不接收这个类型——它只认 middleware.Middleware,也就是 func(middleware.Handler) middleware.Handler。
这个 middleware.Handler 是个函数类型:func(context.Context, any) (any, error),它处理的是「协议无关的请求体」(可能是 HTTP 请求解析后的 struct,也可能是 gRPC 的 req),而不是 *http.Request。
- 错误写法:
func(next http.Handler) http.Handler { ... }→ 编译可能过,但运行时注册会 panic - 正确写法:
func(next middleware.Handler) middleware.Handler { ... }→ 才能被http.Middleware()或grpc.Middleware()接受 - 已有 net/http 中间件(如
cors.New())必须用transport.HTTPMW()包装转换,否则上下文透传失效
transport.FromContext(ctx) 是获取请求元信息的唯一可靠方式
Kratos 把 HTTP 方法、路径、gRPC 方法名、客户端地址等都统一塞进 context.Context,但不是通过 http.Request 拿,而是靠 transport.FromContext(ctx) 提取一个 transport.Transport 实例。
如果你在中间件里写 r.URL.Path 或 r.Method,那说明你还在用原生思维——这在 Kratos 里不可靠,尤其当启用了自动 content-type 路由或 proto over HTTP 时,*http.Request 可能已被多次包装或解码,原始字段已失真。
- 要取路径:用
transport.FromContext(ctx).Operation()(返回类似/helloworld.v1.Greeter/SayHello或/helloworld/{name}) - 要取客户端 IP:用
transport.FromContext(ctx).RemoteAddr(),不是r.RemoteAddr - 要区分协议:检查
transport.FromContext(ctx).Kind()返回值是transport.KindHTTP还是transport.KindGRPC
多个中间件组合时,执行顺序是「从右往左」嵌套
Kratos 的 middleware.Chain() 实现是倒序遍历中间件切片,也就是说:middleware.Chain(m1, m2, m3) 的实际调用链是 m3 → m2 → m1 → handler。
这个顺序直接影响前置/后置逻辑的生效时机。比如你写了日志、鉴权、耗时统计三个中间件,又希望「耗时统计」包住整个流程(含鉴权和日志),那它就必须放在最右边;反之,如果想只统计业务 handler 耗时,就得把它放最左边。
- 推荐显式用
middleware.Chain()组合,别依赖http.Middleware()的参数顺序直觉 - 调试时可在每个中间件开头加
log.Debugw("enter", "middleware", "xxx")和结尾加log.Debugw("exit", "middleware", "xxx")验证顺序 - 注意:
recovery.Recovery()必须放在最外层(即 Chain 切片最右),否则 panic 无法被捕获
中间件里不能直接操作 http.ResponseWriter,要靠 transport.ServerOption 注册
有人想在中间件里写 w.WriteHeader(401) 或 json.NewEncoder(w).Encode(...),这是错的。Kratos 的中间件不持有 http.ResponseWriter,它的 Handler 签名里只有 context.Context 和请求体,响应体是靠框架最后统一序列化返回的。
真正需要干预 HTTP 响应头、状态码、编码格式的地方,应该走 transport.ServerOption,比如:
- 统一设置 CORS 头:用
http.CORS()(不是中间件) - 自定义错误响应格式:实现
transport.ErrorEncoder并传给http.ErrorEncoder() - 强制返回 JSON 而非 proto:配置
http.Codec()使用json.Codec - 修改默认 404 响应:提供自定义
http.NotFoundHandler
把响应控制逻辑塞进中间件,等于绕过 Kratos 的协议抽象层,后续切换 gRPC 或增加 OpenAPI 支持时会立刻崩掉。


















