Golang Web项目目录结构推荐与布局方案

在 Golang Web 项目中，推荐使用模块化目录结构提升可维护性与协作效率。1. cmd/ 目录存放程序入口，每个子目录对应一个可执行程序，main.go 保持简洁仅用于初始化；2. internal/ 存放核心业务逻辑，按 config、handler、model、service 等功能划分，封装实现细节并增强测试性；3. pkg/ 包含可复用的公共库，保持低耦合并对外暴露基础设施能力；4. web/ 管理静态资源与模板文件，适用于页面渲染场景；5. 其他如 migrations、.env、go.mod 和 README.md 等辅助文件也应合理组织以支持开发与部署。这种结构兼顾扩展性、可测试性与团队协作，适合中小型项目采用。

在 Golang Web 项目中，组织结构清晰、模块分明的目录布局不仅能提升团队协作效率，也能让后期维护更轻松。一个推荐的标准目录布局方案应兼顾可扩展性、可测试性和代码的可读性。

下面是一个常见但实用的目录结构模板：

mywebapp/
├── cmd/
│   └── mywebapp/
│       └── main.go
├── internal/
│   ├── config/
│   │   └── config.go
│   ├── handler/
│   │   └── user.go
│   ├── model/
│   │   └── user.go
│   ├── service/
│   │   └── user_service.go
│   ├── middleware/
│   │   └── auth.go
│   └── util/
│       └── logger.go
├── pkg/
│   └── somepkg/
├── web/
│   ├── static/
│   ├── templates/
│   └── public/
├── migrations/
├── .env
├── go.mod
└── README.md

这个结构适用于大多数中小型 Web 应用，接下来我们从几个关键部分来看看为什么要这样组织。

1. cmd/ 目录：程序入口统一管理

Golang 推荐将主函数放在 cmd/ 目录下，每个子目录对应一个可执行程序。比如你有多个服务（如 API 服务和后台任务），可以分别放在 cmd/api/ 和 cmd/worker/ 中。

• main.go 只负责初始化依赖并启动服务，不做具体业务逻辑。
• 有利于区分“可执行文件”和“库代码”。

建议：

• 不要在 main.go 中写太多逻辑，保持简洁。
• 如果项目只有一个服务，目录名通常与项目名一致，例如 cmd/mywebapp/。

2. internal/ 目录：核心业务逻辑存放地

这是项目的核心部分，所有业务逻辑都放在这里。Go 语言规定 internal/ 下的包不能被外部引用，这有助于保护内部实现细节。

常见的子目录包括：

• config/：配置加载，比如数据库连接、环境变量处理。
• handler/ 或 api/：HTTP 路由处理函数。
• model/ 或 entity/：数据模型定义，常用于 ORM 映射。
• service/：业务逻辑层，解耦 handler 和 model。
• middleware/：中间件，如鉴权、日志记录等。
• util/：工具类函数，如字符串处理、时间格式化等。

建议：

• 按功能模块划分目录，比如 user/ 下包含 handler, model, service。
• 避免 handler 层直接操作数据库，通过 service 层调用。
• 使用接口抽象 service，便于单元测试。

3. pkg/ 目录：公共库或工具包

如果你有一些通用的代码希望被其他项目复用，可以放到 pkg/ 目录下。这部分代码对外公开，适合封装一些基础设施能力，比如数据库连接池、日志封装、通用 HTTP 客户端等。

建议：

• 保持高内聚低耦合，避免依赖 internal/。
• 为每个功能模块单独建包，比如 pkg/db, pkg/logger。

4. web/ 目录：静态资源与模板

如果项目包含前端页面渲染（非纯 API 服务），可以把静态资源和模板放在 web/ 下。

• static/：CSS、JS、图片等静态文件。
• templates/：HTML 模板文件。
• public/：公开访问的静态资源目录（如 robots.txt）。

建议：

• 使用 Go 的 html/template 包加载模板。
• 静态文件服务可以通过 http.FileServer 挂载。

5. 其他常见目录与文件

• migrations/：数据库迁移脚本，配合像 golang-migrate/migrate 使用。
• .env：环境变量配置文件（注意不要提交到 Git）。
• go.mod：Go Modules 管理文件。
• README.md：项目说明文档，对新成员友好。

基本上就这些。这种结构虽然不是强制标准，但在实际开发中非常实用，也容易上手。刚开始可能觉得有点复杂，但随着项目规模变大，你会发现这样的分层设计能帮你省去不少麻烦。