Iris 路由中正则约束必须用 {name:type regexp(...)} 语法,type 须为内置宏类型(如 uint64、string),regexp 内不加 / 和 flag,匹配整个参数值;不匹配则直接 404,handler 不执行。

iris 路由中怎么写正则约束?用 {param:type regexp(...)} 语法
iris 不支持在路径里直接写裸正则(比如 /user/([0-9]+)),必须通过参数宏(macro)语法嵌入。核心格式是:{name:type regexp(正则表达式)},其中 type 是基础类型(如 string、uint64),regexp(...) 是可选的正则校验部分。
常见写法示例:
app.Get("/user/{id:uint64 regexp(^[1-9][0-9]{0,18}$)}", handler)
app.Get("/slug/{name:string regexp(^[-a-z0-9]{3,32}$)}", handler)
app.Get("/file/{filename:string regexp(^.*\.pdf$)}", handler)
注意点:
-
regexp(...)中的括号必须是英文圆括号,且不能嵌套; - 正则表达式本身不加
/开头结尾,也不加g、i等 flag; - 整个正则匹配的是该参数的**全部值**(即锚定在
^和$之间),不需要手动加; - 如果只写
{id:string},它会接受任意非斜杠字符,等价于{id:string regexp(.*)},但 iris 不推荐这样写,因为缺乏校验。
为什么 {id:int} 不生效?类型名必须用 iris 内置 macro 名
iris 的类型不是 Go 原生类型别名,而是 macro 注册名。写 {id:int} 或 {id:integer} 都会报错或退化为 string,因为 iris 没注册这些名字。
必须使用它文档里明确列出的 macro 类型:
-
{id:uint64}→ 匹配无符号整数(推荐用于 ID) -
{id:int64}→ 匹配带符号整数(含负号) -
{name:string}→ 匹配任意非/字符串 -
{uuid:string regexp(^[da-f]{8}-[da-f]{4}-[da-f]{4}-[da-f]{4}-[da-f]{12}$)}→ 自定义 UUID 格式
错误示例:/post/{id:int} 会导致该路由永远不匹配,请求被跳过或落到 fallback 路由(比如 NotFound handler)。
当代理已经知道网站路由或内容URL,并且在启动前需要有效的sitemap XML、sitemap索引或robots.txt引用时,请使用sitemap。这是一个发布构件技能,而不是爬虫或SEO平台。
正则不匹配时会发生什么?默认返回 404,不进 handler
iris 在路由匹配阶段就完成正则校验 —— 它不是在 handler 里用 ctx.Params().GetXXX() 时才检查,而是在 URL 解析时就决定“这条路通不通”。
这意味着:
- 请求
GET /user/abc到/user/{id:uint64}→ 直接 404,handler 根本不会执行; - 请求
GET /user/0到/user/{id:uint64 regexp(^[1-9])}→ 也 404(因为 0 不满足开头非零); - 没有自动 fallback 到更宽泛的路由,哪怕你同时注册了
/user/{id:string}; - 如果你想做兜底,得显式注册一个更低优先级的路由,比如放在后面、用通配符
/user/{rest:path}。
性能影响大吗?和纯静态路由比,正则匹配开销很小
iris 底层用的是 muxie 路由器,它的正则匹配不是每次请求都编译 regex,而是启动时预编译并缓存。只要正则写得合理(不包含回溯灾难型表达式,比如 (a+)+b),性能几乎和静态路由持平。
但要注意:
- 避免在同一个路径段反复用多个
regexp宏,比如/{a:string regexp(...)}-{b:string regexp(...)}/{c:string regexp(...)}; - 优先用内置类型(如
uint64)代替string regexp,前者解析更快、更安全; - 如果正则逻辑复杂(比如要验证邮箱、中文、混合长度),建议放到 handler 里做业务校验,而不是塞进路由约束 —— 路由层只做“格式粗筛”,handler 做“语义精验”。
最易被忽略的一点:正则里的转义必须双写,比如匹配反斜杠要写 regexp(^\\)$(Go 字符串字面量 + 正则引擎双重转义),实际很少需要,但一旦用到就容易卡住半天。


















