Golang项目目录结构搭建教程

本文系统介绍了Go语言项目中广受社区认可的目录结构初始化实践，强调通过cmd/、internal/、pkg/、api/、configs/、scripts/等职责分明的顶层目录实现代码与配置分离、业务域驱动的包组织、环境感知的配置加载以及就近可运行的测试与统一构建管理，既规避了Java式分层陷阱和循环依赖风险，又兼顾可维护性、可测试性与工程扩展性，为Go开发者提供了一套轻量实用、开箱即用的项目骨架指南。

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 接口，而非具体实现）。

配置管理：代码与配置分离，环境感知加载

不硬编码配置，也不把 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）

不复杂但容易忽略

以上就是《Golang项目目录结构搭建教程》的详细内容，更多关于的资料请关注golang学习网公众号！