Iris路由注册必须显式调用app.Get等方法,否则handler永不触发;路径参数须用ctx.Params().Get()获取,且名称大小写敏感;动态参数需配合路由宏(如{id:uint64})实现匹配阶段校验。

路由注册必须显式调用 app.Get、app.Post 等方法
不调用 app.Get 或类似方法,业务函数永远不会被触发。Iris 不会自动扫描函数名或结构体标签来绑定路由——所有映射都靠显式注册完成。
常见错误现象:写了 handler 函数,也写了 app := iris.New(),但服务启动后访问路径返回 404 或直接超时。根本原因是漏掉了注册语句。
-
app.Get("/user/{id:uint64}", userHandler)是标准写法;app.Handle("GET", "/user/{id}", userHandler)也可用,但更冗长 - HTTP 方法必须匹配:用
app.Post注册的 handler,只响应 POST 请求,GET 访问必然 404 - 路径中含动态参数(如
{id:uint64})时,handler 函数签名必须是func(ctx iris.Context),不能少参数或改类型
ctx.Params().Get 是取路径参数的唯一正确方式
别用 ctx.URLParam("id"),它只读 ?id=123 这类查询参数,对 /user/123 完全无效。路径参数统一走 ctx.Params()。
容易踩的坑:
- 参数名大小写敏感:
app.Get("/user/{ID}")后必须用ctx.Params().Get("ID"),写成"id"返回空字符串 - 没做类型校验就直接强转:
ctx.Params().GetInt("id")可能 panic,应优先用GetIntDefault("id", 0)或配合路由宏(如{id:uint64})让匹配阶段就过滤非法值 - 若路由定义为
/files/{path:path},ctx.Params().Get("path")返回的是完整子路径(如"a/b/c.txt"),且不含 URL 解码,需手动调用url.PathUnescape
分组路由用 app.Party 挂载,不是嵌套函数调用
app.Party("/api") 返回的是一个新路由组对象,不是“进入作用域”的语法糖。所有子路由必须挂在这个返回值上,而不是写在花括号里靠缩进隐式归属。
典型错误写法:
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景,三层路由架构(触发词→SAD反馈→DAG编排),recall@10=96.97%。配置驱动(chains.yaml),零代码扩展。pip install skill-weave-chains 一键安装。
api := app.Party("/api")
{
app.Get("/users", handler) // ❌ 错:仍注册到根路由,不是 /api/users
}
正确写法:
api := app.Party("/api")
api.Get("/users", handler) // ✅ 对:注册到 /api/users
api.Post("/users", handler)
- 中间件可一次性加在分组上:
api.Use(authMiddleware),之后所有子路由自动继承 - 分组支持嵌套:
v1 := api.Party("/v1"),生成/api/v1/xxx路径 - Party 第二个参数是可选的前置中间件函数,不是“初始化逻辑”,别在里面写业务代码
handler 执行完必须让 Iris 知道请求结束
Iris 的 iris.Context 是复用对象,handler 返回即视为该请求生命周期终结。如果 handler 内部没写任何响应(如漏掉 ctx.JSON()),Iris 会默认返回空响应体 + 200 状态,前端可能卡住或收不到数据。
关键点:
- 不要在 handler 里调用
panic或未捕获错误——Iris 会 recover 并断开连接,但日志里只有堆栈,无业务上下文 - 若需提前终止,用
ctx.StopExecution()+ 显式写响应,之后别再调ctx.Next()或其他写操作 - 所有写响应的方法(
ctx.JSON、ctx.HTML、ctx.StatusCode(404))都必须在 handler 返回前完成;返回后调用无效
最常被忽略的一点:路由宏(如 {id:int min(1)} 能在匹配阶段拦截非法请求,避免 handler 里反复做边界检查——但前提是路由定义和参数获取方式完全对应,错一个字母或类型就失效。










