中间件函数签名必须严格为func(iris.Context),不可有返回值或多参数;需显式调用ctx.Next()并合理放置位置;注册须在路由定义前,作用域由注册位置决定;数据共享应使用ctx.Values()。

中间件函数签名必须是 func(iris.Context)
写错签名是新手最常卡住的地方,Iris 会直接忽略或 panic。它只认严格匹配 func(iris.Context) 的函数——不能有返回值、不能多参数、不能用 *context.Context 或 error 类型。IDE 提示类型不匹配、启动时报 cannot use xxx as type iris.Handler,基本就是这问题。
正确写法:func(ctx iris.Context) { /* do something */ }
错误写法举例:func(ctx iris.Context) error、func() iris.Handler、func(ctx *context.Context)
必须显式调用 ctx.Next() 才能让请求继续
ctx.Next() 不是“自动跳转”,它只是把控制权交给下一个中间件或 handler;它执行完后,当前函数里后续代码仍会继续运行。这点和 Gin 的 abort() 完全不同,容易误以为写了响应就终止了流程。
- 鉴权失败时,只写
ctx.StatusCode(401)+ctx.JSON(...)是不够的,必须紧跟ctx.StopExecution(),否则业务 handler 仍会执行 -
ctx.Next()应放在所有条件判断之后,且只出现一次;不要写在if分支里(除非你确定该分支要继续) - 漏掉
ctx.Next()的后果是:中间件执行完就停,后续中间件和路由 handler 全部不触发
注册位置决定作用域:全局、分组、路由三级不可混用
Iris 没有“中间件开关”或“排除路径”机制,中间件是否生效,完全取决于你把它注册在哪一级,以及是否被上游提前中断。
-
app.Use(mw):全局生效,对所有路由(包括/health、/swagger)都走一遍 -
api := app.Party("/api/v1"); api.Use(mw):只影响/api/v1/*下的路由,静态资源或根路径不受影响 - 想排除某个子路径(如
/api/v1/health),只能在中间件内部判断ctx.Path()后跳过ctx.Next() - 注册顺序 = 执行顺序:
app.Use(logMw); app.Use(authMw)→ 请求先进 log,再进 auth
用 ctx.Values() 传数据,别碰 ctx.Request().Context()
业务 handler 和中间件之间共享数据,唯一推荐方式是 ctx.Values().Set("key", value)。这个 map 是 per-request 的,线程安全,不用手动清理,也和 Go 原生 context.Context 无关——往后者塞东西,Iris 根本不读。
- 写入:
ctx.Values().Set("user_id", 123) - 读取:
uid := ctx.Values().GetInt64("user_id")(配套方法比类型断言更安全) - 统一响应场景下,handler 主动存
"json_result",中间件末尾取并ctx.JSON()输出 - 别用闭包捕获变量,多个并发请求会互相污染
真正容易被忽略的是:中间件注册语句必须出现在所有 app.Get()、app.Post() 之前;否则它根本不会挂到任何路由上。哪怕只差一行顺序,整个中间件链就失效了。
大量免费API接口:立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游,为数据API应用能力赋能!











