全局中间件应使用app.Use()而非UseGlobal():前者作用于所有已注册路由,后者无条件拦截所有请求;UseGlobal()仅适用于极少数场景,如统一埋点;app.Use()推荐用于日志、鉴权等通用逻辑。

全局中间件必须用 app.Use(),不是 UseGlobal()
绝大多数人第一次写全局中间件时会误以为 UseGlobal() 才是“全局”的正确入口——其实恰恰相反。UseGlobal() 是最高优先级、无条件最先执行的中间件,但它不等于“对所有路由生效”的常规全局中间件;它连 404 路由、静态文件、未注册路径都会拦截。真正日常用的“全局中间件”是 app.Use(),它作用于所有已注册的路由(不含 404),且按注册顺序执行。
-
app.Use():推荐用于日志、鉴权、跨域等通用逻辑,只影响你app.Get()/app.Post()等明确定义的路由 -
app.UseGlobal():慎用,仅适合极少数场景,比如统一埋点、强制请求头改写、或调试时捕获所有进入路由器的原始请求 -
app.Done()是响应阶段钩子,不属于请求流转链,不能替代Use()做前置处理
ctx.Next() 必须显式调用,漏掉就中断整个请求链
中间件函数签名固定为 func(iris.Context),无返回值。Iris 不自动推进流程——你必须在该放的位置写 ctx.Next(),否则后续中间件和最终 handler 完全不会执行。常见错误是把它写在条件分支里却忘了兜底,或者提前 return 后没加 ctx.StopExecution()。
- 判断失败需终止:先写响应,再调
ctx.StopExecution(),最后return(StopExecution()不会自动退出函数) - 判断通过才继续:把
ctx.Next()放在所有if分支之后、函数末尾之前 - 不要写成
func() error或带返回值的签名,Iris 会直接 panic
全局中间件无法绕过路由分组中间件,但可被 Party() 局部覆盖
中间件执行顺序是:全局(app.Use())→ 分组(party.Use())→ 路由级(内联 handler)。这意味着即使你注册了全局中间件,某个 Party("/admin") 还是可以再加自己的 Use(auth),两者叠加执行,不会互相屏蔽。
- 想让某分组跳过全局中间件?不行——Iris 没提供“跳过”机制,只能在全局中间件内部做路径判断并
ctx.Next()直通 - 想让某条路由完全不用任何中间件?只能单独定义一个无中间件的
Party,或把 handler 写成app.Get("/public", handler)(不传中间件参数) - 多个
app.Use()调用按代码顺序依次执行,顺序错会导致鉴权在日志前、CORS 在压缩后等逻辑混乱
调试时最容易忽略:404 和 OPTIONS 预检也被 app.Use() 拦截
app.Use() 对所有匹配到的路由生效,包括你没显式定义的 OPTIONS 方法(浏览器预检)和最终 fallback 的 404 处理器。如果你的中间件里有强校验逻辑(比如检查 token),而没对 OPTIONS 或 /not-found 做放行,就会导致 CORS 失败或 404 页面返回 401。
- 检查
ctx.Method()和ctx.Path(),对OPTIONS直接ctx.Next()放行 - 避免在中间件里写
ctx.StatusCode(404),Iris 的 404 是最后 fallback,手动设状态码不等于触发 fallback - 用
app.Logger().Infof("path: %s, method: %s", ctx.Path(), ctx.Method())快速确认哪些路径实际进了中间件


















