Go项目推荐采用cmd/internal/pkg/config/api/web/scripts/tests等分层目录结构，其中cmd存入口、internal放私有业务逻辑、pkg供外部复用、config管配置、api定义接口、web托管前端资源、scripts管理自动化任务、tests存放集成测试，go.mod须置于根目录声明模块。
准备一个 Golang 项目的基础目录结构时，重点是保持清晰、可维护和符合社区通用规范。虽然 Go 官方没有强制规定项目结构，但经过多年实践，已经形成了一些被广泛接受的最佳实践。下面是一套实用且易于扩展的目录结构方案。
基础目录结构示例
一个典型的 Go 项目可以按照以下方式组织：
/├── cmd/
│ └── appname/
│ └── main.go
├── internal/
│ ├── service/
│ ├── handler/
│ └── model/
├── pkg/
│ └── util/
├── config/
│ └── config.yaml
├── api/
│ └── v1/
├── web/
│ └── static/
│ └── templates/
├── scripts/
│ └── deploy.sh
├── tests/
├── go.mod
├── go.sum
├── README.md
└── Makefile
各目录作用说明
理解每个目录的用途有助于合理组织代码：
- cmd/：存放程序入口。每个子目录对应一个可执行文件。例如 cmd/api/ 启动 HTTP 服务，cmd/worker/ 启动后台任务。
- internal/：私有代码。Go 规定该目录下的包不能被外部模块导入，适合存放核心业务逻辑。
- pkg/：可复用的公共工具包。这些代码设计为可被其他项目导入，比如日志封装、时间处理等。
- config/：配置文件，如 YAML、JSON 或环境变量加载逻辑。
- api/：API 接口定义，特别是与 OpenAPI/Swagger 配合时有用。
- web/：前端资源，如静态文件和模板（用于 HTML 渲染服务）。
- scripts/：自动化脚本，如构建、部署、数据库迁移等。
- tests/：存放端到端测试或集成测试脚本，单元测试通常直接放在对应包内。
go.mod 的位置
go.mod 应位于项目根目录，标识模块的根路径。它定义了模块名和依赖关系，是 Go Modules 工作的基础。例如：
立即学习“go语言免费学习笔记（深入）”；
module github.com/yourname/projectname go 1.21 require ( github.com/gin-gonic/gin v1.9.1 github.com/spf13/viper v1.16.0 )模块名建议使用完整的仓库地址，便于他人引用。
实用建议
- 从简单开始。初期不需要所有目录，按需创建。
- 避免将所有东西塞进根目录。随着项目增长，混乱的结构会显著增加维护成本。
- 使用 internal 保护核心代码不被误导出。
- 如果项目提供 SDK 或工具库，把可导出的部分放到 pkg/ 并写好文档。
- 结合 Makefile 简化常用命令，如 build、test、run。
基本上就这些。一个好的目录结构不会一蹴而就，但在项目初期建立清晰的组织方式，能有效支撑后续迭代。参考主流开源项目（如 Kubernetes、Prometheus）的结构也有助于提升设计水平。
