静态路由必须注册在动态路由之前，因Gin按注册顺序和最长前缀匹配，若/user/:id先注册，则/user/create等静态路径将被错误捕获。
静态路由必须注册在动态路由之前
Gin 的路由匹配不是靠正则精确度，而是靠注册顺序 + 最长前缀匹配。一旦 /user/:id 这类带参数的动态路由先注册，后续的 /user/create 就永远无法被命中——因为前者已经把整个 /user/xxx 都吃掉了。
常见错误现象：
- 前端访问
/user/create却进了GetUserHandler，c.Param("id")返回"create" - 日志里反复出现
id=create，但业务逻辑完全错乱
实操建议：
- 所有纯静态路径（如
/healthz、/favicon.ico、/user/create）必须在任何:param或*wildcard路由前注册 - 按路径字面长度倒序排列：先写
/users/activate，再写/users/:id，最后写/users/:id/orders - 用
router.Any("/debug/pprof", ...)这类调试路由时，也要严格放在动态路由之前
Group 里的子路由也遵循相同顺序规则
router.Group("/api") 创建的分组本身不改变匹配优先级，它只是路径前缀拼接器。组内路由仍按注册顺序执行，且和全局路由共享同一匹配队列。
使用场景：
- 版本化 API：
v1 := r.Group("/api/v1")后注册的v1.GET("/users", ...)和v1.GET("/users/:id", ...)依然要遵守“静态优先” - 权限隔离：
admin := r.Group("/admin")下的/admin/dashboard必须比/admin/:page先注册
容易踩的坑：
- 误以为 Group 是独立命名空间，把
/admin/:id写在/admin/login前面，结果登录页返回 404 - 在不同 Group 中注册了冲突路径，比如
r.GET("/status", ...)和v1.GET("/status", ...)，后者实际永远不会触发（因前者已匹配）
避免用 *wildcard 覆盖正常路径
:param 至少会校验斜杠分隔，而 *filepath 是贪婪匹配，连中间的斜杠都吞掉。一个 GET("/static/*filepath") 放太靠前，可能让 /api/v1/users 都被截胡。
Skill Weave Chains — 技能链路由引擎
下载
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
性能与兼容性影响：
-
*filepath匹配开销明显高于:param，尤其在高并发下易成瓶颈 - 某些中间件（如 CORS、JWT 验证）依赖路径结构做判断，被 wildcard 扰乱后行为不可控
实操建议：
- 静态文件服务尽量用
r.StaticFS("/static", ...)，它内部做了路径预检，不参与主路由匹配队列 - 真要用
*filepath，务必放到所有业务路由之后，且加明确前缀（如/files/*filepath），避免裸根/*filepath - 上线前用
curl -v http://localhost:8080/xxx手动测几个关键静态路径，确认没被意外捕获
调试路由匹配顺序的两个有效方法
Gin 不提供内置的路由表 dump，但可以通过启动日志和手动断点快速定位问题。
说明：
- Gin 默认只在 debug 模式下打印注册日志，但不显示最终匹配顺序；你看到的 “Registered GET:/user/:id” 只是注册动作，不代表它在匹配队列里的位置
- 真正起作用的是
gin.(*node).getValue的遍历逻辑，它从 root 开始按注册顺序逐个比对
实操建议：
- 启动时加
gin.SetMode(gin.DebugMode)，观察日志中各路由注册的先后顺序 - 在 handler 开头加
log.Printf("hit: %s, path=%s", c.Request.Method, c.Request.URL.Path)，对比请求实际进哪个 handler - 对关键路径写单元测试，用
httptest.NewRecorder()模拟请求，断言rec.Code是否为预期状态码
最常被忽略的一点：路由顺序问题不会报错，只会静默错配。上线后前端调用失败，后端日志却显示“成功处理”，这种无声的错位最难排查。
