Beego路由匹配按注册顺序线性扫描，具体路由须置于通配路由前；同一路径可绑定多方法但需显式声明；参数名须完全一致；静态资源请求不走常规路由，应使用BeforeStatic钩子。
路由注册顺序直接影响匹配结果
Beego 的路由匹配是按注册顺序线性扫描的，一旦某条路由成功匹配，后续路由将被跳过。这意味着更宽泛的路由（如 /api/*）如果写在前面，会吞掉后面更具体的路由（如 /api/users/:id）。常见现象是：访问 /api/users/123 却进了 ApiCatchAllController，而不是预期的 UsersController。
解决办法很简单：把具体路由放前面，通配路由放最后。例如：
beego.Router("/api/users/:id", &controllers.UsersController{}, "get:GetUser;put:UpdateUser")
beego.Router("/api/posts/:id", &controllers.PostsController{}, "get:GetPost")
beego.Router("/api/*", &controllers.ApiCatchAllController{})
- 不要用
/api/:path代替/api/*—— 前者只匹配一级路径，后者才真正通配任意深度 - 若需正则约束（如仅允许数字 ID），用
/api/users/:id([0-9]+)，避免:id匹配空字符串或非数字导致误判 - Beego v2 中可通过
beego.BeeApp.Handlers.Routes查看当前已注册路由的原始顺序，调试时可打印验证
相同路径不同方法的路由不会冲突，但需显式声明
很多人误以为 beego.Router("/login", &c.LoginController{}) 和 beego.Router("/login", &c.LoginController{}, "post:DoLogin") 会冲突，其实不会——Beego 允许同一路径绑定多个 HTTP 方法，前提是第三个参数中明确写出方法映射。否则，默认只注册 GET。
典型错误是只写了基础路由，却期望 POST 也能走同一个控制器：
// ❌ 错误：只注册了 GET，POST 请求直接 405
beego.Router("/login", &controllers.LoginController{})
// ✅ 正确：显式声明所有需要的方法
beego.Router("/login", &controllers.LoginController{}, "get:ShowLogin;post:DoLogin")
- 方法名必须首字母大写，且控制器中对应函数签名不能带
http.ResponseWriter或*http.Request参数（Beego 1.x/v2 均如此） - 若混用
*和具体方法（如"*:Handle;post:DoLogin"），Beego 会优先匹配post，不会 fallback 到* - 测试时注意：单元测试中若未导入
routers包，即使代码写对了也看不到任何路由注册，务必加空白导入_ "your-project/routers"
动态参数命名不一致会导致匹配失败而非冲突
路由定义里的参数名（如 :id）和控制器里取参时用的名字（c.Ctx.Input.Param(":id")）必须完全一致，包括冒号和大小写。Beego 不做模糊匹配或别名转换，名字错一个字符，Param() 就返回空字符串，容易误判为“没匹配上”。
常见陷阱：
- 路由写成
/user/:userId，控制器却写c.Ctx.Input.Param(":id")→ 拿不到值 - 用了正则但没注意捕获组边界，比如
/file/:name([a-z]+).txt，当请求/file/report.json时，因后缀不匹配而跳过该路由，落到下一个规则 - 路径中含下划线（如
/cms_:id.html），控制器仍要用":id"取值，不是":cms_id"
建议统一用短小、语义清晰的参数名（如 :id、:slug），避免拼写变体。
静态资源路由与 API 路由共存时的过滤时机差异
Beego 对 /static/ 下的请求有独立处理流程，它不走常规路由表，也不触发 BeforeRouter 过滤器。如果你写了 beego.Router("/static/private/*", ...)，这条路由永远不会生效——因为静态文件请求根本不会进入 Router 匹配阶段。
正确做法是用 beego.BeforeStatic 钩子，例如：
beego.InsertFilter("/static/private/:id([0-9]+)/", beego.BeforeStatic, controllers.CheckAuth)
-
BeforeStatic是唯一能拦截静态资源请求的时机，此时c.Ctx.Request.URL.Path可读，但c.Input.Session()不可用，需手动调用c.StartSession() - 不要试图用
beego.Router覆盖/static/路径，Beego 会优先走内置静态服务，你的路由会被静默忽略 - 若需完全接管静态资源（比如加权限、审计日志），应关闭 Beego 默认静态服务：
beego.BConfig.WebConfig.StaticDir = make(map[string]string)，再用自定义路由+文件读取逻辑实现
路由冲突本身不报错，它只是让请求悄悄落入你没意识到的处理器里。最危险的情况是：你以为 /admin/* 被保护了，结果因顺序或命名问题，某个 /admin/export 请求绕过了鉴权直接执行了导出操作。
