Iris路由参数必须显式声明类型宏(如{id:uint64})才能触发校验与强转,否则默认为字符串且无校验;提取时键名大小写敏感,path类型需放路径末尾并手动解码。

Iris 的路由参数不是靠“配置”出来的,而是靠在路由路径里写明类型宏、再用对应方式提取——不写类型,就只是字符串;写了类型,才触发校验和强转。
路由路径中必须显式声明参数类型宏
Iris 不会自动推断 {id} 是整数还是字符串。默认按 {id:string} 处理,但这样无法拦截非法值,也无法安全转成 int64 等类型。
- 合法写法:
/user/{id:uint64}、/post/{slug:alphabetical}、/files/{path:path} - 错误写法:
/user/{id}(无类型 → 无校验,后续强转可能 panic) - 多个参数可混用:
/api/v1/{year:int}/{month:int}/{day:int} - 自定义宏需先注册,再使用,例如
{oid:int min(1) max(999999)}要求值在 1–999999 之间
提取参数时必须匹配路由中定义的键名
ctx.Params().Get("id") 中的 "id" 必须和路由里花括号内的名字完全一致,大小写敏感。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景,三层路由架构(触发词→SAD反馈→DAG编排),recall@10=96.97%。配置驱动(chains.yaml),零代码扩展。pip install skill-weave-chains 一键安装。
- 若路由是
/order/{OrderID:uint64},就必须用ctx.Params().Get("OrderID"),不能用"orderid"或"orderid" - MVC 控制器中用
By前缀时也一样:{uid:int64}→ 方法参数写ByUid int64,不是Byuid或ByUID - 拼错或大小写不对,值就是零值(如
0、空字符串),且无任何报错提示
path 类型参数必须放路径末尾,且需手动解码
{p:path} 是唯一能捕获多级子路径的宏,但它有硬性约束和隐含行为。
- 必须放在路径最末端:
/static/{file:path}✅,/static/{file:path}/meta❌(编译报错) - 返回的是原始 URL 编码字符串,比如请求
/static/a%20b/c.txt,ctx.Params().Get("file")得到的是"a%20b/c.txt",不是"a b/c.txt" - 需要自己调用
url.PathUnescape解码,否则空格、中文等都会出问题
类型宏决定你是否要检查 err
用没用类型宏,直接决定你在取值时要不要处理错误。
- 路由写
/user/{id:uint64}→ 可放心用ctx.Params().GetUint64("id"),失败即 404,不会进 handler,err永远为 nil - 路由写
/user/{id}→ 即使用GetUint64("id"),也可能返回err != nil,必须检查,否则用id会 panic - 想兜底又不想写 err 判断?用
GetIntDefault("id", -1)这类带默认值的方法
真正容易被忽略的是:类型宏不是“语法糖”,它是 Iris 路由匹配阶段的硬校验开关。没开它,后面所有强转都得自己兜底;开了它,404 就发生在进 handler 之前,而不是运行时 panic 之后。


















