Buffalo默认404不触发中间件链，需在app.Use末尾加兜底中间件判断c.Param("_matched")为空时返回结构化JSON；同时须前置校验API版本、禁用静态文件路由、避免模板渲染panic。
Buffalo 默认 404 行为不触发中间件链
Buffalo 的 app.NotFoundHandler 是一个裸函数，它在路由完全未匹配时直接执行，绕过所有中间件（包括日志、CORS、auth）。这意味着你无法在 404 响应里统一加 trace_id、记录请求路径或做灰度降级。常见现象是：访问 /api/v1/missing 返回空响应体 + 404 状态码，但日志里找不到这条请求。
实操建议：
- 不要只依赖 app.NotFoundHandler = func(c buffalo.Context) error { return c.Error(404, errors.New("not found")) }
- 在 app.Use() 链末尾插入自定义兜底中间件，用 c.Request().URL.Path 判断是否已匹配（c.Param("_matched") 为空则表示未命中）
- 若未匹配，手动调用 c.Status(404) 并返回结构化 JSON：{"error": "route_not_found", "path": "/xxx"}，避免裸字符串
带版本前缀的路由未匹配时容易漏掉 v1/v2 分流逻辑
企业项目通常要求 /api/v1/ 和 /api/v2/ 路由隔离，但 Buffalo 默认路由系统不会自动拦截非法版本路径。比如请求 /api/v3/users，若没显式定义 v3 路由，它会 fallback 到 NotFoundHandler，而不是返回明确的版本错误。
实操建议：
- 在 app.Use() 中添加前置校验中间件，正则匹配 ^/api/(v\d+)/
- 提取版本号后查白名单（如 map[string]bool{"v1": true, "v2": true}），不合法则立即 c.Status(400) 并返回 {"error": "unsupported_api_version"}
- 不要把这个逻辑塞进 NotFoundHandler，否则 v3 请求会先走完整中间件链再 404，浪费资源
静态文件路由与 API 路由冲突导致假性 404
Buffalo 默认启用 app.ServeFiles("/assets/*x")，但若你删了 assets/ 目录又没注释这行，任何以 /assets/ 开头的请求（比如前端发错的 /assets/api/v1/users）都会被该 handler 拦截并返回 404 —— 此时 NotFoundHandler 根本不执行，且无日志提示。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
实操建议：
- 精简 Buffalo 为纯 API 时，必须删除或注释 app.ServeFiles() 调用
- 检查 public/ 目录是否存在，若不存在且没禁用静态服务，http.FileServer 会静默失败
- 用 curl -v http://localhost:3000/assets/xxx 测试是否真返回 404，还是 net/http 默认的 directory list 页面
自定义 404 响应必须避开模板渲染路径
Buffalo 的 c.Render() 默认尝试加载 HTML 模板，若你没删 templates/ 目录但又想返回 JSON 404，会触发 template: "not_found.html" is undefined panic；若删了目录又没重写 Render，则 panic 报错更隐蔽。
实操建议：
- 纯 API 项目中，所有 404 响应改用 c.JSON(404, map[string]string{"error": "not found"})
- 不要复用 r.Auto(c, ...)，它会根据 Accept header 自动选 HTML/JSON，而浏览器发的请求 header 里总带 text/html
- 若需保留类型协商能力，自己实现简易协商逻辑：if strings.Contains(c.Request().Header.Get("Accept"), "application/json") { c.JSON(...) } else { c.PlainText(404, "not found") }
真正难处理的是「部分匹配」——比如 /api/v1/users/:id 匹配成功但 :id 类型校验失败（期望 UUID 却收到数字），这种错误不会进 NotFoundHandler，得靠参数绑定中间件提前拦截。
