go项目推荐采用cmd/、internal/、pkg/、api/、configs/、scripts/等目录结构，按业务域组织包，配置与代码分离，测试文件与源码同目录，构建用makefile统一管理。
Go 项目目录结构没有官方强制规范，但社区已形成成熟、可扩展的实践模式。关键在于按职责分离、避免循环依赖、便于测试和部署。
核心目录划分（推荐基础结构）
一个清晰的 Go 项目通常包含以下顶层目录：
-
cmd/：存放可执行程序入口（main.go），每个子目录对应一个二进制文件（如
cmd/myapp、cmd/myworker） - internal/：仅限本项目使用的私有包，外部无法 import（Go 1.4+ 强制保护）
- pkg/：可被其他项目复用的公共包（导出接口稳定、有文档、带单元测试）
- api/ 或 proto/：API 定义（OpenAPI spec）、gRPC proto 文件及生成代码
-
configs/：配置文件模板与默认值（如
configs/config.yaml、configs/config.local.yaml.example） - scripts/：部署、生成、检查等辅助脚本（bash / make / golangci-lint 配置）
-
go.mod 和 go.sum：根目录下初始化模块（
go mod init example.com/myapp）
包组织原则：小而专注，按领域而非技术分层
避免按 controller/service/repository 这类 Java 风格分层。Go 更倾向按业务域或功能边界组织包：
- 用户相关逻辑 →
internal/user（含 user.User 结构、注册/登录逻辑、密码加密等） - 订单处理 →
internal/order（含 Order 结构、状态机、支付回调处理器） - 共享工具 →
pkg/util（非业务通用函数，如时间格式化、JSON 辅助、错误包装） - 数据库访问 →
internal/storage或internal/repo（封装 SQL / ORM 调用，不暴露 driver 细节）
每个包应有明确职责，go list ./... 应能直观反映依赖关系；内部包之间通过接口解耦（如 order.Service 依赖 user.Repository 接口，而非具体实现）。
立即学习“go语言免费学习笔记（深入）”；
配置管理：代码与配置分离，环境感知加载
不硬编码配置，也不把 config struct 放在 main 包里。推荐做法：
- 定义配置结构体在
configs/config.go，使用 struct tag 标注 yaml/json key - 用
github.com/spf13/viper或原生gopkg.in/yaml.v3+os.ReadFile加载 - 支持多环境：优先读取
config.$ENV.yaml（如config.prod.yaml），再 fallback 到config.yaml - 敏感字段（如 DB password）通过环境变量注入，配置文件中留空或占位（
password: ${DB_PASSWORD}）
测试与构建：保持就近与可运行性
测试文件与源码同目录（user.go 与 user_test.go 并列），测试包名加 _test 后缀仅当需跨包测试时使用。
- 单元测试覆盖核心逻辑，用
testify/assert或原生testing即可 - 集成测试放在
internal/integration/，启动真实依赖（如 SQLite 内存 DB、mock HTTP server） - 构建脚本写在
Makefile中：make build（编译所有 cmd）、make test（运行全部测试）、make lint（golangci-lint）
不复杂但容易忽略
