Buffalo路由需显式带版本前缀（如/api/v1/users）并禁用硬编码，否则无法支持灰度、审计与平滑升级；路径不匹配、漏注册OPTIONS、中间件顺序错误均导致404或静默失败。
Buffalo 的路由不是“注册完就自动生效”的黑盒，app.GET 写错路径、漏版本前缀、中间件顺序放错，请求直接 404 或静默失败——根本进不到你的 handler 里。
为什么 app.GET("/users", handler) 在生产环境会出问题
这个写法在开发阶段看起来能跑，但企业级 API 要求版本可演进、路径可审计、错误可拦截。/users 这种无版本路径一旦上线，后续加 v2 就只能改代码、发版、停服，客户端全量升级。Buffalo 不强制版本，也不做运行时路由分发，它只做静态匹配：路径字符串完全一致才进 handler。
- 路径必须显式带版本前缀，比如
/api/v1/users，且所有地方用常量（如UserListPath = "/api/v1/users"），禁止字符串字面量散落 -
app.Group("/api/v1", ...)看似隔离，实则只是路径拼接封装，无法支持灰度、无法集中审计、无法运行时切换 - 若想动态加载路由（比如从 etcd 或 DB 读配置），得替换底层 router（如用
gorilla/mux），再把 Buffalo 的 action 封装成http.HandlerFunc注册进去
请求匹配失败的三个典型现象和对应检查点
Buffalo 的路由匹配发生在任何中间件之前，所以 404 不是 handler 报的，而是框架根本没找到 route。常见表现有：
- 浏览器显示 404，但日志里压根没打印请求——说明没匹配到 route，连中间件都没进
- 写了
app.Options("/api/users", ...)却收不到预检请求——因为 OPTIONS 必须显式注册，Buffalo 不自动 fallback - WebSocket 连接失败，控制台只报
WebSocket connection to 'ws://...' failed，无其他提示——大概率是中间件提前写了 header，导致 Upgrade 失败
检查顺序应为：路径字符串是否完全一致 → 是否漏了 app.Options → 是否有中间件（如日志、gzip）在 handler 前调用了 WriteHeader() 或写入了 body。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
中间件注册顺序直接影响请求能否走到 handler
Buffalo 的 app.Use() 是链式执行，越早注册的中间件越先执行，但也越容易“拦住”请求。比如版本校验中间件必须放在最前面，否则非法 /api/v3/xxx 请求可能被 auth 中间件先处理，再抛 401 而非 404。
- 版本校验中间件要放在
app.Use()第一个位置，用strings.HasPrefix判断，别用正则（避免回溯爆炸） - CORS 配置不能只靠全局中间件——OPTIONS 预检和 WebSocket Upgrade 都绕过中间件链，必须在路由层显式注册
app.Options和直连app.GET("/ws", handler) - panic 捕获中间件也要尽早注册，但注意区分
buffalo.Error（业务错误，不该 recover）和真实 panic（如 nil pointer）
路由定义必须脱离硬编码，否则没法做灰度和审计
把所有 app.GET 散落在 routes/app.go 里，上线后改个路径就得发版；想给 v2 接口导流 5% 流量，也做不到。真正的可维护做法是让路由规则外置。
- 不依赖
app.Routes()返回值（它是只读的），改用gorilla/mux初始化自定义http.Handler，再把 Buffalo 的buffalo.Context封装进去 - 若坚持用内置路由，至少把 path 提取为常量，统一管理；handler 函数名也建议用
UsersListHandler这类命名，便于 grep 审计 - 旧接口冻结但不删除，比如
UserListPathV1和UserListPathV2同时存在，确保兼容性
真正难的不是写对一行 app.GET，而是让整个路由系统能支撑灰度、审计、降级、迁移——这些能力 Buffalo 默认不提供，得靠结构设计补上。
