Buffalo框架项目开发目录结构解析-Golang-PHP中文网

buffalo 默认目录结构为事实标准：根下含actions/（控制器，函数须接收*buffalo.context）、templates/（路径映射url，如home/index.html对应get /home）、public/（静态资源根目录）、models/（pop orm表定义与迁移）、main.go等；约定严格，路径须全小写无下划线，否则静默失败。

buffalo框架项目开发目录结构解析

Buffalo 框架没有官方强制的“标准目录结构”，但其 CLI 生成的项目骨架已形成事实上的工程惯例——直接照搬它，能避开 80% 的路由加载失败、模板找不到、静态资源 404 等问题。

buffalo new 生成的默认结构长什么样

执行 buffalo new myapp 后，你会得到类似这样的根目录：

myapp/
├── actions/
│   ├── app.go
│   └── home.go
├── grifts/
├── models/
│   └── models.go
├── public/
│   ├── assets/
│   └── robots.txt
├── templates/
│   ├── application.html
│   └── home/index.html
├── Dockerfile
├── buffalo.dev.yml
├── database.yml
├── go.mod
└── main.go

关键点：

actions/ 是控制器层，不是 controllers/ —— 这是 Buffalo 特有的命名，函数必须接收 *buffalo.Context，返回 error
templates/ 下的文件路径直接映射 URL：比如 templates/home/index.html 对应 GET /home（由 actions/home.go 中的 HomeHandler 渲染）
public/ 是静态资源根目录，/assets/ 里放打包后的 JS/CSS；开发时用 buffalo dev 会自动构建并托管
models/models.go 默认使用 Pop（Buffalo 官方 ORM），表定义和迁移都写在这里，不是分散在多个文件

为什么 templates 路径必须和 action 函数名严格匹配

Buffalo 的模板渲染依赖约定优于配置：调用 c.Render(200, r.HTML("home/index.html")) 时，框架会去 templates/ 下找对应路径。但更常见的是隐式匹配：

Buffalo框架 1.0.1

Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。

下载

如果 actions/home.go 里定义了 func Home(c buffalo.Context) error，且没显式调用 Render，Buffalo 会自动尝试渲染 templates/home/index.html
路径中每级目录名必须小写，且不能含下划线或大写字母，否则 buffalo dev 启动时报 template not found
application.html 是默认 layout，所有子模板用时会套用它 —— 注意不是 yield 或 content_for

如何安全地拆分 actions 和 models

CLI 生成的结构适合小项目，但中大型项目需要解耦。不要手动改 actions/ 下的包名或移动文件，Buffalo 的 buffalo dev 依赖固定导入路径：

想分模块？在 actions/ 下建子目录，如 actions/api/v1/users.go，但必须确保该文件顶部是 package actions，且 main.go 中仍通过 app.GET("/api/v1/users", UsersIndex) 注册
models 层不建议拆包：Pop 的 db.Create() 依赖全局 TX，跨包初始化容易导致 panic: no connection found
业务逻辑别塞进 action：新建 app/services/ 目录（不在 Buffalo 默认结构里），放纯 Go 函数，由 action 调用 —— 这里可以自由组织，不受框架约束

buffalo dev 和 buffalo build 的目录行为差异

开发和构建阶段对目录的处理逻辑完全不同，这是最易踩坑的地方：

buffalo dev：实时监听 actions/、templates/、public/assets/ 变化，自动重编译；但 public/ 下非 assets/ 的文件（如 public/favicon.ico）不会被自动复制到构建产物中
buffalo build：只打包 public/assets/ 和 templates/ 到二进制内嵌资源，其他 public/ 文件会被忽略 —— 如果你放了 public/manifest.json，上线后 404 是必然的
解决方案：用 buffalo build --static 生成完整静态文件树，或把非 assets 资源移到 public/assets/ 下再引用