Go项目目录结构最佳实践指南

专注于 Golang 相关文章和资料的开源项目 go-home ，欢迎关注！

在Go项目开发中，良好的目录结构对项目的可维护性和团队协作至关重要。本文基于社区广泛认可的项目布局标准，介绍Go项目的目录组织最佳实践。
1. 核心应用目录 - /cmd

项目的主要应用程序入口点应放在/cmd目录下。每个应用程序都应该有自己的子目录：

1. /cmd
2.   /myapp
3.     main.go     // package main
4.   /myworker
5.     main.go     // package main

复制代码

每个子目录名应该与生成的可执行文件名一致。main.go文件应该尽量简洁，实际的业务逻辑应该导入自/internal或/pkg目录。
2. 私有代码目录 - /internal

私有应用代码和库代码放在/internal目录。Go编译器会强制执行这个目录的访问控制，其他项目无法导入internal目录下的包：

1. /internal
2.   /app
3.     /myapp        // 应用私有代码
4.   /pkg
5.     /database     // 内部共享库
6.     /auth         // 认证模块

复制代码

这是Go语言级别的保护机制，确保内部实现不会被外部项目依赖。
3. 公共库目录 - /pkg

可以被外部项目导入的库代码放在/pkg目录：

1. /pkg
2.   /httputil       // HTTP工具库
3.   /stringutil     // 字符串处理工具
4.   /errors         // 错误处理包

复制代码

使用/pkg目录时要谨慎，确保这里的代码确实适合对外公开，并且有良好的API设计和文档。
4. 依赖管理 - /vendor

使用vendor目录管理项目依赖（如果启用了vendor模式）：

1. # 启用vendor模式
2. go mod vendor
4. # 使用vendor构建
5. go build -mod=vendor

复制代码

现代Go项目通常使用Go Modules，vendor目录变为可选。
5. API定义目录 - /api

API定义文件、协议文件放在/api目录：

1. /api
2.   /openapi
3.     swagger.yaml     # OpenAPI规范
4.   /proto
5.     user.proto       # Protocol Buffers定义
6.   /graphql
7.     schema.graphql   # GraphQL schema

复制代码

6. 配置文件目录 - /configs

配置文件模板或默认配置：

1. # /configs/config.yaml
2. server:
3.   host: localhost
4.   port: 8080
5. database:
6.   driver: postgres
7.   dsn: postgres://localhost/mydb

复制代码

注意：实际的配置文件（包含敏感信息）不应该提交到版本控制。
7. 部署相关目录

部署和构建相关的文件分别组织在不同目录：

1. /build
2.   /ci              # CI配置文件
3.     .travis.yml
4.   /package         # 打包脚本
5.     Dockerfile
7. /deployments
8.   /docker-compose
9.     docker-compose.yml
10.   /kubernetes
11.     deployment.yaml

复制代码

8. 脚本目录 - /scripts

各种构建、安装、分析等脚本：

1. /scripts
2.   build.sh         # 构建脚本
3.   install.sh       # 安装脚本
4.   test.sh          # 测试脚本
5.   lint.sh          # 代码检查

复制代码

9. 测试目录 - /test

额外的外部测试应用和测试数据：

1. /test
2.   /integration     // 集成测试
3.   /e2e            // 端到端测试
4.   /testdata       // 测试数据文件
5.   /mocks          // 模拟对象

复制代码

单元测试应该与被测试的代码在同一个包中，使用_test.go后缀。
10. 其他常用目录

文档和工具相关目录：

1. /docs           # 项目文档
2.   design.md     # 设计文档
3.   api.md        # API文档
5. /tools          # 项目工具
6.   /gen          # 代码生成工具
8. /examples       # 示例代码
9.   simple.go     # 基础示例
10.   advanced.go   # 高级用法
12. /assets         # 静态资源
13.   /images       # 图片
14.   /templates    # 模板文件

复制代码

11. 不推荐的做法

避免以下目录结构：

1. # 不要使用src目录
2. /src  ❌
4. # 避免在根目录放置过多Go文件
5. main.go  ❌ (除非是简单的单文件项目)
6. server.go ❌
7. handler.go ❌

复制代码

Go项目不需要Java风格的src目录，直接在项目根目录组织代码即可。
12. 实际项目示例

一个典型的Web服务项目结构：

1. myproject/
2. ├── cmd/
3. │   └── server/
4. │       └── main.go
5. ├── internal/
6. │   ├── handler/
7. │   │   └── user.go
8. │   ├── model/
9. │   │   └── user.go
10. │   └── service/
11. │       └── user.go
12. ├── pkg/
13. │   └── logger/
14. │       └── logger.go
15. ├── api/
16. │   └── openapi.yaml
17. ├── configs/
18. │   └── config.yaml
19. ├── deployments/
20. │   └── docker-compose.yaml
21. ├── scripts/
22. │   └── build.sh
23. ├── go.mod
24. ├── go.sum
25. └── README.md

复制代码

总结

良好的项目结构能够提高代码的可维护性、可测试性和团队协作效率。虽然这不是Go官方强制的标准，但已经被社区广泛采用。在实际项目中，应该根据项目规模和团队需求，选择合适的目录结构，避免过度设计。小型项目可以从简单结构开始，随着项目增长逐步完善目录组织。

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！