app.Use()是注册全局中间件的唯一入口,按注册顺序执行且必须显式调用ctx.Next()和ctx.StopExecution();app.UseGlobal()优先级最高但无序,仅适用于底层预处理。

app.Use() 是注册全局中间件的唯一入口
Iris 不区分“前置/后置”中间件类型,app.Use() 注册的函数会在所有匹配路由的 handler 执行前调用;若需在 handler 后执行逻辑,得用 app.Done() ——但它不是“后置中间件”,而是响应已写出后的钩子,不能修改响应体或状态码。
常见错误是把日志、认证等逻辑混进 Done(),结果发现 ctx.StatusCode() 失效、ctx.JSON() 报错:因为响应头已发送,无法再写入。
-
app.Use()中必须显式调用ctx.Next(),否则后续 handler 完全不执行 - 若中间件提前返回(如鉴权失败),必须紧跟着
ctx.StopExecution(),否则 Iris 仍会继续执行下一个中间件甚至路由 handler - 多个
app.Use()调用按注册顺序依次执行,先注册的先运行
全局中间件里忘记 ctx.StopExecution() 会导致静默错误
比如 JWT 认证中间件校验失败后只写了 ctx.StatusCode(401) 和 ctx.WriteString("unauthorized"),但没调 ctx.StopExecution(),Iris 会继续执行后续中间件和路由 handler,可能造成重复响应、panic 或数据泄露。
正确模式固定为三段式:
func authMiddleware(ctx iris.Context) {
token := ctx.GetHeader("Authorization")
if token == "" {
ctx.StatusCode(401)
ctx.WriteString("missing Authorization header")
ctx.StopExecution() // ✅ 必须有
return
}
// ...校验逻辑
ctx.Next() // ✅ 放在所有 return 之后
}
注意:ctx.StopExecution() 不会中断 Done() 钩子,那些仍会运行。
UseGlobal() 和 Use() 的执行优先级差异
app.UseGlobal() 注册的中间件优先级最高,总是在所有 app.Use() 和路由分组中间件之前执行。它适合做统一请求预处理(如强制 HTTPS 重定向、请求 ID 注入),但不适合做业务相关拦截(如权限判断),因为太早,还没走到具体路由上下文。
-
app.UseGlobal()→app.Use()→ 分组Use()→ 路由 handler - 所有
UseGlobal()中间件都共享同一个执行时机,无顺序保证(不建议注册多个) - 若某中间件需跳过特定路径(如 /health),必须在中间件内部用
ctx.Path()判断并主动ctx.Next(),不能靠“不注册”来绕过
路由分组中间件不是全局中间件,别混淆作用域
很多人误以为 admin.Use(auth) 是“局部全局”,其实它只影响该 Party 下注册的所有路由,对 /api/users 这类未挂载到 admin 分组的路径完全无效。真正的全局中间件只有 app.Use() 和 app.UseGlobal()。
容易踩的坑:
- 在
app.Party("/api")里调Use(),却期望它对/webhook生效 → 不会 - 把 CORS 中间件只注册在
api.Use()里,但前端请求的是/static/*→ 预检失败 - 用
UseGlobal()做用户认证 → 因为还没解析路由,无法知道是否需要鉴权,容易误拦健康检查接口
真正需要全局生效的逻辑(如日志、CORS、请求 ID),务必走 app.Use();UseGlobal() 只用于极底层、与业务完全解耦的操作。


















