Iris中全局中间件仅通过app.Use()作用于根路由,Party子组不自动继承,必须显式调用各层级Party().Use()补全;Use()须在路由注册完成后、app.Listen()前执行,且参数必须为iris.Handler类型。

全局中间件在 Iris 中不是“自动继承”的概念,app.Use() 只作用于直接注册在该 iris.Application 实例上的路由;所有通过 Party() 创建的子路由组默认不带父级中间件,必须手动补上。
app.Use() 是唯一真正的“全局”挂载点
只有调用根应用实例的 Use(),才能让中间件覆盖所有未被子组隔离的路由。比如:
app := iris.New()
app.Use(loggingMiddleware) // ✅ 对 /、/health、/api(如果没用 Party 分离)都生效
app.Get("/", homeHandler)
app.Get("/health", healthHandler)
但一旦你用了 Party(),这个“全局性”就断了:
-
v1 := app.Party("/api/v1")→v1不会自动携带loggingMiddleware - 若忘记
v1.Use(loggingMiddleware),/api/v1/xxx就不会打日志 - 嵌套子组(如
v1.Party("/admin"))更不会继承,必须逐层显式调用
Party().Use() 必须在路由注册完成后立即调用
很多人在 BeforeActivation 钩子里写:
app.OnAnyErrorCode(func(ctx iris.Context) {
admin := app.Party("/admin")
admin.Use(authMiddleware) // ❌ 错!此时 admin 还未激活,Use 无效
admin.Get("/dashboard", dashboardHandler)
})
正确顺序是:先注册完所有子路由,再对 Party 实例调 Use(),且必须在 app.Listen() 或 app.Run() 前执行:
admin := app.Party("/admin")admin.Get("/dashboard", dashboardHandler)admin.Post("/user", createUserHandler)-
admin.Use(authMiddleware)✅ 放在这儿才有效
注意:Use() 接收的是 iris.Handler 类型函数,不是字符串或闭包调用结果。常见错误写法:admin.Use(authMiddleware()) —— 如果 authMiddleware() 返回的是 func(iris.Context) 才对;如果它返回的是另一个类型(如 func() iris.Handler),就会 panic。
CORS 和 OPTIONS 预检必须显式配对处理
Iris 没有内置 CORS 中间件,也不能靠中间件单点注入头就完事。因为预检请求(OPTIONS)若未在路由表中注册,中间件根本不会触发。
所以必须两步走:
- 用
app.Options("*", corsHandler)或app.Options("/api/*", corsHandler)显式注册通配 OPTIONS 路由 - 在
corsHandler中完整设置响应头:Access-Control-Allow-Origin、Access-Control-Allow-Methods、Access-Control-Allow-Headers,并返回204 No Content - 若需带凭证(
withCredentials: true),Access-Control-Allow-Origin不能为"*",得写死具体 origin(如"http://localhost:3000")
漏掉任一 header 或 method,前端都会报 Response to preflight request doesn't pass access control check。
中间件内写响应后必须调 ctx.StopExecution()
Iris 不像 Gin 那样自动中断后续链。如果你在鉴权中间件里写了 ctx.JSON(401, ...) 却没跟 ctx.StopExecution(),控制流仍会往下走,可能进到业务 handler,造成重复响应或逻辑错乱。
典型反模式:
func authMiddleware(ctx iris.Context) {
if !isValidToken(ctx) {
ctx.JSON(401, map[string]string{"error": "unauthorized"})
ctx.Next() // ❌ 千万别加这句
return
}
ctx.Next() // ✅ 只在放行时调
}
更安全的写法是用条件包裹:if isValidToken(ctx) { ctx.Next() },避免任何隐式执行分支。
真正容易被忽略的是:子路由组的中间件必须手动补全,没有“继承”这回事;而 BeforeActivation 钩子只适合定义结构,不是绑定行为的时机。


















