Li6Daily

Appearance

2026-01-12
886
3.2m

Golang 项目目录结构说明 ​

本文用于梳理当前 Golang 项目的整体目录布局与职责划分，目的是提高项目的可维护性、可读性以及团队协作效率。该结构参考了 Go 官方推荐实践，并结合实际工程经验进行取舍与约定。

一、项目根目录结构 ​

text
.
├── app/
├── bin/
├── configs/
├── docs/
├── internal/
├── scripts/
├── test/
├── utils/
├── go.mod
└── go.sum

二、目录职责说明 ​

1. app/ ​

用于存放应用入口层代码，通常对应不同的可执行程序（binary）。

常见用途：

  • 不同服务的 main.go
  • CLI 工具入口
  • 按应用名称再做一层子目录划分

示例：

text
app/
├── api-server/
│   └── main.go
└── worker/
    └── main.go

该目录应保持“薄”，只负责启动、参数解析、依赖初始化，不承载业务逻辑。

2. bin/ ​

用于存放编译后的二进制文件。

约定：

  • 不参与版本控制（通常加入 .gitignore）
  • 仅作为本地调试或 CI 构建产物输出目录

3. configs/ ​

用于集中存放配置文件。

常见内容：

  • YAML / JSON / TOML 配置
  • 不同环境配置（dev / test / prod）

示例：

text
configs/
├── config.yaml
├── config.dev.yaml
└── config.prod.yaml

建议配置结构保持稳定，避免在代码中散落硬编码参数。

4. docs/ ​

用于存放项目相关文档。

包括但不限于：

  • 架构设计说明
  • 接口文档
  • 数据结构或协议说明
  • 开发规范与约定

该目录是代码之外的“第二事实来源”，建议与代码同步维护。

5. internal/ ​

用于存放项目内部核心代码，这是整个项目的主体。

特点：

  • Go 编译器层面限制外部项目引用
  • 适合放置业务逻辑、领域模型、基础组件

常见拆分方式：

text
internal/
├── service/
├── handler/
├── repository/
├── model/
├── middleware/
└── pkg/

是否按“领域”还是“技术层”拆分，可根据项目规模与团队习惯决定，但应保持一致性。

6. scripts/ ​

用于存放辅助脚本。

常见用途：

  • 构建脚本
  • 部署脚本
  • 数据迁移或初始化脚本

示例：

text
scripts/
├── build.sh
├── deploy.sh
└── init_db.sh

脚本应尽量幂等，并附带必要注释。

7. test/ ​

用于存放集成测试或端到端测试代码。

说明：

  • 与 Go 原生的 _test.go 单元测试区分
  • 适合需要完整环境依赖的测试场景

例如：

text
test/
├── api_test.go
└── integration/

8. utils/ ​

用于存放通用工具代码。

使用建议：

  • 仅放与具体业务无关的通用能力
  • 若 utils 逐渐膨胀，应考虑拆分为 internal 下的独立模块

典型示例：

  • 时间处理
  • 编码转换
  • 通用校验函数

三、Go Modules 文件说明 ​

go.mod ​

  • 定义模块名称
  • 声明 Go 版本
  • 描述直接依赖关系

是整个项目依赖管理的核心入口文件。

go.sum ​

  • 记录依赖的校验信息
  • 保证依赖版本的可重复构建

该文件应提交到版本控制中，不建议手动修改。

四、其他约定 ​

根目录还可以放必要的文件，如：Makefile、README.md等。

五、总体设计原则 ​

  • 入口与业务分离：app 只做启动，internal 承载逻辑
  • 边界清晰：内部代码不被外部依赖
  • 目录即约定：结构本身就是文档
  • 可演进性：允许随着项目增长逐步细化，而不是一开始过度设计

本文档可作为项目初始模板或团队统一约定的参考，根据实际业务复杂度灵活调整。

最近更新