中间件必须按执行顺序显式注册,顺序错误会导致鉴权跳过、日志漏打、panic捕获失效;注册顺序即执行顺序,recover需置首,auth在logging后、handler前,errorHandler置尾;ctx.Next()不可遗漏,否则链中断。

多个中间件必须按执行顺序显式注册,Iris 不会自动合并或排序,顺序错就导致鉴权跳过、日志漏打、panic 捕获失效。
中间件注册顺序决定执行顺序
Iris 中间件是链式调用的,ctx.Next() 控制是否继续向后传递。注册顺序 = 执行顺序,且不可逆。
- 先注册的中间件最先执行,比如
app.Use(recover.New())必须在最前,否则 panic 无法捕获 - 身份校验中间件(如
authMiddleware)应放在日志中间件之后、业务 handler 之前,否则未登录用户也会被记日志 - 错误处理中间件(如
errorHandler)通常放最后,靠ctx.StatusCode()或ctx.IsStopped()判断是否已响应
同一 Party 下多次调用 Use() 是合法且常用的做法
不要试图把所有逻辑塞进一个中间件函数里。拆分职责更易调试和复用:
-
app.Use(loggingMiddleware)—— 记录请求路径、耗时、状态码 -
app.Use(corsMiddleware)—— 设置 Access-Control-* 头 -
app.Use(authMiddleware)—— 解析 token 并挂载用户信息到ctx.Values().Set("user", u) - 每个中间件只做一件事,
ctx.Next()前后可加日志确认是否进入/退出
嵌套 Party 的中间件叠加规则
子分组中间件不会覆盖父分组,而是追加在父分组之后执行:
-
admin := app.Party("/admin")调了admin.Use(auth)→ 所有/admin/*先跑auth -
users := admin.Party("/users")又调了users.Use(rateLimit)→ 实际执行顺序是auth → rateLimit → handler - 若
users还想跳过auth(比如开放注册接口),不能删父级Use(),而应单独建无认证分组:public := app.Party("/public")
中间件内部 ctx.Next() 被遗漏的典型表现
这是最隐蔽也最常踩的坑:中间件函数没调 ctx.Next(),后续中间件和 handler 就完全不执行,但 HTTP 状态码可能是 200(因中间件自己写了响应)。
- 现象:
/api/v1/users接口返回空内容或超时,日志里只看到第一个中间件的日志 - 检查点:所有中间件函数体末尾是否有
ctx.Next()?条件分支里是否每个分支都覆盖了? - 反例:
if !isValid(ctx) { ctx.StatusCode(401); return }—— 缺少else { ctx.Next() },后续全中断 - 建议:在中间件开头加
ctx.Application().Logger().Infof("→ %s", ctx.Path()),结尾加ctx.Application().Logger().Infof("← %s", ctx.Path()),快速定位断点
中间件链不是“配置列表”,而是运行时确定的函数调用栈。任何一层漏掉 ctx.Next() 或顺序颠倒,都会让整条链失效——它不像配置项可以 reload,改完就得重启服务验证。











