通配符路由必须位于路径末尾,如 /static/*filepath;不可出现在中间,否则报 invalid pattern 错误。因 fiber 的 radix tree 要求通配节点为子节点末位,且不与参数或静态节点同级共存。

通配符路由只能放在路径末尾
Fiber 不允许 *path 出现在中间段,比如 /files/:user/*path 或 /api/v1/*version/users 都会触发启动报错:invalid pattern。引擎只接受形如 /static/*filepath、/uploads/*rest 这种“前缀 + 通配”结构。
原因在于 Fiber 的基数树(radix tree)设计:通配节点必须是子节点列表的最后一个,且不能与参数节点(:id)或静态节点同级共存。一旦出现非末尾通配,树结构无法确定匹配优先级。
-
/files/*a✅ 合法,c.Params("a")返回"/some/nested/path" -
/files/*a/b❌ 启动失败,*后不能再有其他段 -
/v1/:id/*rest✅ 合法,:id是参数节点,*rest是其唯一子节点 -
/v1/*rest/:id❌ 语法错误,*必须收尾
*path 和 +path 返回值差异
两者都捕获剩余全部路径,但处理前导斜杠的方式不同:
-
*path:返回值带前导/,例如请求/assets/js/app.js匹配/assets/*file→c.Params("file")得到"/js/app.js" -
+path:返回值不带前导/,同样请求 →c.Params("file")得到"js/app.js"
如果你后续要拼接本地文件路径(如 os.Open("static" + path)),用 +path 更安全;若需保留原始 URL 结构做代理转发,*path 更直接。
通配符和参数节点不能混写在同一段
Fiber 路径解析是段级匹配,不是正则。这意味着你不能写 /posts/:id/comments/*rest —— 这看起来合理,但实际 :id 和 *rest 是两个独立节点类型,引擎不允许在同一个路径层级同时声明。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景,三层路由架构(触发词→SAD反馈→DAG编排),recall@10=96.97%。配置驱动(chains.yaml),零代码扩展。pip install skill-weave-chains 一键安装。
常见误写及替代方案:
-
/api/:version/*path✅ 正确:参数节点 + 通配子节点 -
/api/:version/:section/*rest✅ 正确:两层参数 + 通配 -
/api/:version*rest❌ 错误:冒号和星号紧挨着,解析器直接拒绝 -
/api/v2/*rest✅ 静态前缀 + 通配,适合版本固化场景
如果需要动态提取多级路径(如 /api/v2/users/123/profile),应拆成 /api/:version/:resource/:id/:section,而不是强行塞通配符。
StrictRouting 开启时通配路由仍受斜杠影响
即使用了 *path,StrictRouting = true(默认)下,请求末尾多一个 / 仍可能不匹配。例如:
- 路由定义:
app.Get("/files/*path", handler) - 请求
GET /files/a/b.txt→ 命中 - 请求
GET /files/a/b.txt/→ 404(注意末尾斜杠)
这是因为基数树匹配的是完整路径段,/files/a/b.txt/ 最后一段是空字符串,而 *path 捕获的是“非空剩余路径”。解决方式只有两个:
- 显式注册带斜杠变体:
app.Get("/files/*path/", handler) - 用中间件统一 strip 末尾斜杠(推荐,避免重复注册)
别关 StrictRouting 来迁就通配——它会影响整个路由树的歧义控制,尤其当存在 /users 和 /users/:id 这类易冲突路由时。










