在 Go 项目开发中。糟糕的目录结构会导致：

• 新人无法快速定位业务入口，学习成本飙升；
• 代码耦合度提高，修改一个模块往往要牵连大量文件；按理说，
• 依赖管理混乱。建立/部署频繁出错，其实，

这篇文章基于社区大家认可的布局标准。提供一套「最佳」目录结构，让团队协作更顺畅、代码更易维护。

. 主要应用目录 - /cmd

痛点：很多项目把所有可执行文件都放在根目录，导致入口文件杂乱不堪。按理说，

将每个可执行程序的入口统一放在 /cmd 下并为每个二进制创建独立子目录。

// 项目根目录结构示例
/cmd
/myapp
main.go // package main
/myworker
main.go // package main

子目录名称必须与生成的可执行文件名保持一致。Main.go 只负责启动和依赖注入，业务实现应放在 /internal 或 /pkg 中。

. 私有代码目录 - /internal

痛点：内部实现被误当成公共库。被外部项目错误引用，引发兼容性问题。

/internal 为 Go 编译器提供了天然的访问限制，只能被同一模块内部使用。

/internal
/app
/myapp // 应用私有代码
/pkg
/database // 内部共享库
/auth // 认证模块

利用此机制可以防止内部细节泄漏到外部项目，提高代码安全性。不过，

. 公共库目录 - /pkg

痛点：缺乏明确的公共库位置。导致团队成员随意在根目录创建工具包，难以统一管理。

/pkg 用来存放明确面向外部使用的库，需要具备良好的 API 设计和完整文档。

/pkg
/httputil // HTTP 工具库
/stringutil // 字符串处理工具
/errors // 错误处理包

. 依赖管理 - /vendor

痛点：依赖版本不统一导致建立机器出现「找不到包」的错误。

If you enable vendoring mode:

# 启用 vendor 模式
go mod vendor
# 使用 vendor 建立
go build -mod=vendor

现代 Go 项目推荐使用 Go Modules（go.mod/go.sum)。/vendor

. API 定义目录 - /api

/api
/openapi
swagger.yaml # OpenAPI 规范
/proto
user.proto # Protocol Buffers 定义
/graphql
schema.graphql # GraphQL schema

# 示例：/configs/config.yaml
说到server，host: localhost
说到port。8080
database:
driver的观点是，postgres
说到dsn，postgres://localhost/mydb?sslmode=disable

/build # 建立产物、CI 脚本等
/ci # CI 配置
/package # 打包脚本
/deployments # 部署编排
docker-compose.yml
kubernetes/
deployment.yaml
service.yaml

/scripts
build.sh # 项目建立
install.sh # 环境安装依赖
test.sh # 单元/集成测试入口
lint.sh # 静态检查

/test
/integration // 集成测试套件
/e2e // 端到端测试套件
/testdata // 测试数据
/mocks // 自动生成或手写的 Mock 实现

/docs # 项目文档
│ design.md # 架构设计文档
│ api.md # API 使用教程
/tools # 辅助工具。如代码生成器、lint 插件
/gen # 自动生成的代码
/examples # 示例程序或演示脚本
│ simple.go # 基础示例
│ advanced.go # 高级用法
/assets # 静态资源
│ /images
│ /templates

. 实际项目示例

myproject/
├── cmd/
│ └── server/
│ └── main.go # 程序入口，仅做初始化 & DI
├── internal/
│ ├── handler/
│ │ └── user.go # HTTP Handler。仅供本项目使用
│ ├── model/
│ │ └── user.go # 数据模型
│ └── service/
│ └── user.go # 业务服务层
├── pkg/
│ └── logger/
│ └── logger.go # 对外可复用的日志封装
├── api/
│ └── openapi.yaml # 对外发布的接口规范
├── configs/
│ └── config.yaml # 配置模板
├── deployments/
│ └── docker-compose.yaml
├── scripts/
│ └── build.sh # CI 常用脚本
├── go.mod
├── go.sum
└── README.md

.

• A clean directory layout dramatically improves 可维护性、可测试性和团队协作效率**；
• The structure presented is **社区共识** 而非官方强制，可根据项目规模灵活裁剪；
• Simplify for small projects—start with /cmd + internal + go.mod + README.md**;expand gradually as codebase grows.
• Avoid over‑engineering: unnecessary层级会适得其反，让新人迷失方向。
• If you encounter “找不到包” 或 “导入方法冲突”，第一步先检查是否遵循了上述约定。

Pain points vanish once folder hierarchy follows se conventions—your team will spend less time hunting files and more time写业务代码 🚀.