推荐采用 cmd/、internal/、pkg/、api/、configs/、scripts/ 目录结构，根目录含 go.mod；internal 下分 app/、handler/、service/、repo/、model/ 实现关注点分离，强调接口抽象与测试友好。
初始化一个规范的 Go 项目结构，核心是遵循 Go 官方推荐的布局习惯（如 cmd/、internal/、pkg/、api/ 等目录划分），同时兼顾可维护性、可测试性和工具链兼容性。不需要复杂脚手架，手动创建即可，关键是逻辑清晰、职责分明。
基础目录结构建议
一个典型的中小型 Go 服务项目，推荐从以下结构开始：
-
cmd/：存放 main 入口文件，每个子目录对应一个可执行程序（如
cmd/myapp） - internal/：存放仅本项目内部使用的代码（编译器会阻止外部模块 import）
- pkg/：存放可被其他项目复用的公共包（语义稳定、有明确接口）
- api/：存放 OpenAPI/Swagger 定义、proto 文件或 API 路由声明（非必须，但利于协作）
-
configs/：配置文件模板（如
config.yaml.example）和加载逻辑 - scripts/：常用 shell 脚本（如构建、本地运行、数据库迁移）
- go.mod 和 go.sum：在项目根目录初始化模块
初始化命令与关键步骤
在空目录中执行以下命令快速启动：
- 运行
go mod init example.com/myapp（替换为你的真实模块路径） - 创建
cmd/myapp/main.go，写入最简 main 函数并导入内部包（触发依赖识别） - 运行
go build -o ./bin/myapp ./cmd/myapp验证构建通路 - 添加
.gitignore，至少忽略/bin/、/dist/、go.work和编辑器临时文件
按功能分层组织 internal/
internal/ 是项目主干，建议按关注点拆分，避免“一锅炖”：
立即学习“go语言免费学习笔记（深入）”；
-
internal/app/：应用层，协调 handler、service、repo，含启动逻辑（如
app.Run()） - internal/handler/：HTTP/gRPC 请求入口，只做参数解析、响应包装
- internal/service/：业务逻辑核心，不依赖框架，纯 Go 结构体+方法
- internal/repo/：数据访问层，封装 DB/Cache/HTTP Client 调用
- internal/model/：领域模型（DTO、Entity、VO），避免跨层裸 struct 传递
实用小提示
让结构真正好用，注意几个细节：
- 每个
internal/xxx子包应有明确的 interface 定义（比如repo.UserRepo），便于 mock 测试 - 避免在
main.go中写业务逻辑，它只负责初始化依赖、启动服务 - 使用
go:embed加载静态资源（如模板、SQL 文件），不要硬编码路径 - 若用 Wire 或 fx 做依赖注入，在
internal/app/下统一管理 wiring 逻辑
基本上就这些。结构不是越深越好，而是让新人一眼看懂“代码在哪改、测试怎么写、配置从哪来”。初期可以精简，随着模块变多再逐步拆分，保持演进节奏比一步到位更重要。
