Iris中必须用app.Use()注册中间件,不存在app.UseRouter();中间件函数签名须为func(iris.Context),写响应后必须调ctx.StopExecution(),否则会panic;作用域由注册位置决定:app.Use()为全局,Party().Use()仅限该组。

中间件注册必须用 app.Use(),不是 app.UseRouter() 或其他变体
很多人在刚接触 Iris 时会误以为中间件可以像路由一样“挂载到某条路径下”就完事,结果发现日志没打、鉴权没生效。根本原因是:Iris 中只有 app.Use() 才注册全局中间件(对所有匹配路由生效),而 app.UseRouter() 并不存在——那是其他框架的写法,Iris 不支持。
常见错误现象:ctx.Next() 没被调用,导致后续处理器完全不执行;或者中间件函数写了但控制台毫无输出,说明压根没注册成功。
-
app.Use()注册的中间件作用于整个应用(除非手动分组) - 若只想对某组路由生效,得配合
app.Party()使用,比如admin := app.Party("/admin"); admin.Use(authMiddleware) - 中间件函数签名必须是
func(iris.Context),不能漏掉参数或改类型 - 中间件内若写完响应(如
ctx.JSON()或ctx.StatusCode()),必须紧接着调用ctx.StopExecution(),否则后续处理器仍会运行,可能造成重复写响应 panic
ctx.Next() 和 ctx.StopExecution() 的调用时机很关键
中间件执行链是洋葱模型:请求进来时逐层 Next(),响应返回时逐层退出。但很多人只记得 Next(),却忽略「写完响应后必须中断」这个硬性要求。
典型翻车场景:JWT 鉴权中间件校验失败后直接 ctx.JSON(401, ...),但没跟 ctx.StopExecution(),结果请求继续往下走,最终 panic: http: multiple response.WriteHeader calls。
- 仅读取请求、记录日志、注入上下文变量等“无副作用”操作,只需调用
ctx.Next() - 一旦调用了任何写响应的方法(
ctx.WriteString()、ctx.JSON()、ctx.Redirect()等),立刻接ctx.StopExecution() -
ctx.StopExecution()不会跳出函数,它只是告诉 Iris “别再调用后续处理器了”,函数本身还会继续执行完剩余代码(所以别在它后面放业务逻辑)
全局中间件 vs 路由级中间件:注册位置决定作用域
同一个中间件函数,注册位置不同,行为完全不同。这不是 bug,是 Iris 明确设计的控制粒度。
比如你写了一个日志中间件 loggingMiddleware:
- 放在
app.Use(loggingMiddleware)→ 所有路由(包括/health、/metrics)都会打日志 - 放在
app.Get("/api/user", loggingMiddleware, userHandler)→ 仅该路由生效,且顺序固定:先 middleware,再 handler - 放在
app.Party("/api").Use(loggingMiddleware)→ 所有以/api/xxx开头的路由生效
注意:app.Done() 是“响应后钩子”,用于记录耗时、清理资源等,它不参与请求处理链,也不影响 ctx.Next() 行为,别把它和 Use() 混用。
中间件里读参数要用 ctx.Params().Get(),不是 ctx.URLParam()
这是个高频陷阱。Iris 中路径参数(如 /user/{id:int})必须用 ctx.Params().Get("id") 获取;而 ctx.URLParam() 只读 URL 查询参数(?id=123)。混用会导致空字符串或 panic。
更隐蔽的问题是:如果中间件注册在 app.Use(),但某个路由没定义该参数名(比如中间件想取 "tenant",但 /public/home 路由没带 {tenant}),ctx.Params().Get("tenant") 会返回空字符串,不会报错——这会让鉴权逻辑静默失效。
- 路径参数存在性检查应写成
if tenant := ctx.Params().Get("tenant"); tenant != "" { ... } - 不要依赖
ctx.Params().GetString()等带默认值的方法,它掩盖了参数缺失问题 - 若需强制某中间件只对含特定参数的路由生效,应在
Party()分组时就限定路由模式,而不是在中间件里做防御性判断
中间件看似简单,但参数获取方式、执行中断机制、作用域边界这三点,几乎覆盖了 90% 的线上故障原因。尤其是 ctx.StopExecution() 的遗漏,往往要等到压测或上线后才暴露。











