Go项目布局参考指南 #

整理版 - 原文：golang-standards/project-layout

⚠️ 重要声明 #

这不是Go官方标准！Go官方团队没有制定任何项目布局标准！

这只是社区总结的常见模式，仅供参考。Go官方的建议是：

• 保持简单
• 根据项目需要组织代码
• 不要过度设计目录结构

何时使用这种布局 #

• ✅ 中大型项目
• ✅ 多人协作项目
• ✅ 开源项目
• ❌ 学习Go语言
• ❌ 小型玩具项目
• ❌ 概念验证项目

小项目从一个main.go文件开始就足够了

核心Go目录 #

/cmd #

主要应用程序入口

/cmd/
  /myapp/
    main.go
  /worker/
    main.go

• 每个可执行文件一个子目录
• 只包含少量代码，主要用于导入和调用其他包
• 从/internal和/pkg目录导入代码

/internal #

私有代码

/internal/
  /app/
    /myapp/
  /pkg/
    /mylib/

• 不希望被其他项目导入的代码
• Go编译器强制执行的私有包机制
• 可以在项目的任何级别创建internal目录

/pkg #

公共库代码

/pkg/
  /mypubliclib/

• 可以被外部项目导入的代码
• 需要谨慎放置，确保代码质量
• 有争议的目录，不是所有人都认同

服务相关目录 #

/api #

API定义

• OpenAPI/Swagger规范
• JSON Schema文件
• 协议定义文件（gRPC .proto文件）

/web #

Web应用组件

• 静态资源
• 服务器端模板
• 单页应用（SPA）文件

配置和部署 #

/configs #

配置文件

• 配置文件模板
• 默认配置
• 环境相关配置

/deployments #

部署配置

• Docker Compose文件
• Kubernetes配置
• Terraform脚本
• 云部署配置

/build #

构建和CI

/build/
  /ci/
  /package/

• CI配置（Travis、Circle、GitHub Actions）
• 容器镜像配置
• 包构建脚本

辅助目录 #

/scripts #

构建和工具脚本

• 构建脚本
• 安装脚本
• 分析工具脚本

/test #

额外测试文件

• 集成测试
• 测试数据
• 测试工具

/docs #

文档

• 设计文档
• 用户文档
• API文档

/examples #

示例代码

• 使用示例
• 演示代码

/tools #

支持工具

• 项目相关的工具代码
• 可以从/pkg和/internal导入代码

其他目录 #

/vendor #

依赖管理

• go mod vendor创建的依赖副本
• Go 1.14+通常不需要
• 库项目不应提交vendor目录

/assets #

静态资源

• 图片、Logo等资源文件

/third_party #

第三方工具

• 外部工具
• 分叉代码
• 第三方资源

避免的目录 #

❌ /src #

• Java风格的目录结构
• 与Go工作空间的src目录容易混淆
• Go项目中应避免使用

项目布局示例 #

myproject/
├── cmd/
│   ├── server/
│   │   └── main.go
│   └── client/
│       └── main.go
├── internal/
│   ├── app/
│   │   └── server/
│   └── pkg/
│       └── auth/
├── pkg/
│   └── api/
├── api/
│   └── openapi.yaml
├── web/
│   └── static/
├── configs/
│   └── config.yaml
├── deployments/
│   └── docker-compose.yml
├── scripts/
│   └── build.sh
├── docs/
├── test/
└── go.mod

最佳实践建议 #

1. 渐进式采用 #

• 从简单开始
• 随项目增长逐步添加目录结构
• 不要一开始就创建所有目录

2. 根据需要调整 #

• 不是每个项目都需要所有目录
• 根据项目实际情况选择合适的结构

3. 团队约定 #

• 与团队讨论并达成一致
• 建立清晰的代码组织规范

4. 关注依赖关系 #

• cmd → internal + pkg
• internal ← 项目内部使用
• pkg ← 可供外部使用

相关资源 #

• Effective Go - Go官方编写指南
• Go Code Review Comments - Go官方代码评审建议
• Go Modules - Go官方模块系统

争议说明 #

这个项目布局在Go社区存在争议：

• 支持者：认为提供了清晰的组织结构，适合大型项目
• 反对者：认为过度复杂化，违背Go的简洁哲学
• Go官方态度：没有官方推荐，倾向于保持简单

最终建议：这只是参考模式，不是标准。Go官方始终建议保持简单，根据实际需要组织代码。