buffalo 项目目录结构由 buffalo new 命令严格生成，不可随意修改——因编译期与运行期均依赖固定路径：actions/ 注册路由、models/ 执行迁移、templates/ 渲染视图；--api 模式下仅 templates/、assets/、locales/ 可删，models/ 和 actions/ 必须保留；database.yml 仅为占位，真实 db 配置通过环境变量 db_url 注入。
Buffalo 项目开发目录不是靠手动创建或自由命名，而是由 buffalo new 命令一次性生成并锁定职责——改错一个目录名、多建一个无关文件夹，都可能让 buffalo dev 启动失败或迁移不生效。
为什么不能随意调整目录结构
Buffalo 在编译期和运行期都依赖固定路径约定。比如：actions.App() 函数会自动扫描 actions/ 下所有 *.go 文件注册路由；buffalo db migrate 只认 models/ 下的 struct 和 pop/soda 迁移文件；r.HTML("home/index.html") 的路径必须与 templates/home/index.html 完全一致。一旦你把 templates/ 改成 views/，渲染直接 panic。
常见错误现象：
-
buffalo dev启动后访问页面报template not found -
buffalo db migrate提示no migrations found，但 migration 文件明明在models/migrations/ -
buffalo routes输出为空，或只显示GET /一条路由
哪些目录可以删减（仅限 --api 场景）
如果你用 buffalo new myapp --api 创建纯 API 服务，以下目录可安全删除或清空：
-
templates/：删掉，否则buffalo build会尝试加载 Plush 引擎并失败 -
assets/：删掉，避免 Webpack 构建干扰 CI 流程 -
public/：保留但清空内容（它是buffalo build --static的输出目标，非源码） -
locales/：删掉，除非你真做多语言 API（JSON key 翻译意义不大）
注意：models/ 和 actions/ 绝对不能删——哪怕你不用数据库，也要留个空 models/models.go，否则 main.go 中的 actions.App() 初始化会 panic。
config/database.yml 不是配置入口，别往里写密码
config/database.yml 是个文档型占位文件，Buffalo 运行时不读它。真实连接逻辑在 models/pop.go 的 NewDB() 函数里，它默认从环境变量 DB_URL 读取连接串。
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
正确做法：
- 把
database.yml中的password:行删掉或改成password: "${DB_PASSWORD}"（仅作提示） - 开发时在终端执行
export DB_URL="postgres://user:pass@localhost:5432/myapp_development?sslmode=disable" - 生产环境通过 Kubernetes Secrets 或 Docker
--env-file注入DB_URL，绝不提交密钥到代码库
如果硬把密码写进 database.yml 并提交 Git，CI 流水线跑 buffalo db migrate 时会直接暴露凭据——因为 pop 的调试日志默认打印完整连接串。
grifts/ 和 docker/ 目录要按需启用
grifts/ 是任务脚本目录（类似 Rails Rake），但 Buffalo 不自动加载它。你得手动运行 buffalo task db:seed 才会触发 grifts/db.go 里的函数。没写 grift 就别留空文件，否则 buffalo task --help 会报解析错误。
docker/ 下的 Dockerfile 和 docker-compose.yml 是开箱即用的，但有两个坑：
-
Dockerfile默认用FROM golang:alpine编译，若你的 model 依赖 cgo（如 SQLite），得换成golang:alpine并加CGO_ENABLED=1 -
docker-compose.yml中的dbservice 没配restart: unless-stopped，容器崩溃后不会自愈
复杂点在于：目录存在 ≠ 功能启用。Buffalo 的很多子系统（如 asset 打包、模板预编译、任务调度）都是“有文件才加载，没文件就跳过”。所以删目录比注释代码更干净，也更容易被新人一眼看懂边界在哪里。
