routes.go 是唯一可信的路由注册入口，所有路径必须集中定义于此；resource 路由要求方法名（list/show/create/update/destroy）和模板路径（如 templates/posts/index.plush.html）严格匹配；中间件仅对注册所在路由组生效；websocket 路由须直连最外层且绕过所有中间件。
routes.go 是唯一可信的路由注册入口
Buffalo 的路由不是靠 app.GET() 零散拼凑的，所有路径必须集中写在 routes/app.go（或 routes.go）里。这个文件由 buffalo new 生成，app.Routes() 返回的就是它定义的路由树——改别的地方没用，比如在 actions/app.go 里调 app.GET() 不会生效。
常见错误现象：加了新路由但始终 404，检查发现是写在了 actions/users.go 里；或者手动改了 app.Routes() 返回值，结果 panic，因为它是只读对象。
- 正确做法：打开
routes/app.go，在app.Resource("/users", UsersResource)或app.GET("/health", HealthHandler)这类调用处增删 - API 项目建议统一前缀：用
app.Group("/api/v1", func(api buffalo.Group) { ... })包裹全部资源路由，避免漏加版本控制 - 不要依赖注释或配置文件驱动路由——Buffalo 没有 route.yaml 或注解扫描机制
Resource 路由自动绑定对方法名和模板路径有硬性要求
app.Resource("/posts", PostsResource) 看似简单，但它背后有一套严格约定：控制器结构体必须实现 List、Show、Create 等固定方法名，且模板路径必须匹配 templates/posts/index.plush.html，否则静默失败。
容易踩的坑：把 List 写成 Index 或 GetAll，服务不报错但访问 /posts 直接返回空响应；又或者模板放在 templates/posts/list.plush.html，框架找不到就渲染空白页，连 404 都不触发。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
- 方法名只能是这五个：
List、Show、Create、Update、Destroy，大小写、拼写一个字母都不能错 - 模板路径规则固定：
templates/{plural-name}/{action}.plush.html，例如PostsResource.List→templates/posts/index.plush.html - 调试时若页面空白，先运行
buffalo routes确认路由是否注册成功，再检查对应模板文件是否存在
中间件绑定位置决定其作用范围
中间件不是全局生效的，它只对注册时所在的路由组起作用。比如 app.Use(auth.Required) 写在最外层，就会包裹所有路由；但写在 api.Group(...) 里，就只保护 API 路径。
典型误用：想让登录校验只对 /admin/* 生效，却把 auth.Required 放在 app.Use() 顶层，结果连 /login 都被拦截，形成死锁。
- 保护子路径：用
app.Group("/admin", func(admin buffalo.Group) { admin.Use(adminAuth); admin.GET("/dashboard", DashboardHandler) }) - 排除特定路径：不能“跳过”中间件，只能分组隔离——把免认证路由（如
/login、/health）单独提出来，不套进受保护的 Group - 自定义中间件函数必须返回
buffalo.MiddlewareFunc类型，且内部要显式调用c.Next()，否则后续 handler 不执行
WebSocket 路由必须绕过中间件链直接升级
WebSocket 的 Upgrade 协议对 HTTP 响应头极其敏感，任何中间件提前写入 header（比如日志、CORS、gzip）都会导致浏览器连接失败，控制台只显示 WebSocket connection to 'ws://...' failed，无具体错误提示。
这不是 Buffalo 的 bug，而是 HTTP 协议限制：Upgrade 必须是响应的第一帧，不能有任何前置输出。
- 必须把 WebSocket handler 注册在最外层
app.GET("/ws", wsHandler)，且不能经过任何app.Use()或Group.Use() - handler 内部直接调用
upgrader.Upgrade(c.Response().Writer, c.Request(), nil)，禁止使用c.Render()或c.JSON() - 如果需要鉴权，必须在
Upgrade前完成，比如从 query 参数或 cookie 提取 token 并验证，失败就直接return c.Error(401, errors.New("unauthorized"))
buffalo routes，再对照约定逐项核对，比反复刷新页面猜原因快得多。
