1.1 标准项目布局：目录结构与职责划分

在 Go 语言生态中，Standard Go Project Layout 并非官方强制规范，但已成为社区广泛认可的最佳实践。它为大型业务项目提供了清晰的模块边界，使团队在协作时能够快速定位代码、降低耦合、提升可维护性。本章将逐一拆解核心目录的作用与职责。

1.1.1 顶层目录全景图

一个遵循标准布局的 Go 项目，其顶层结构通常如下：

my-go-project/
├── cmd/                # 应用入口（main 函数）
├── internal/           # 私有应用逻辑（禁止外部导入）
├── pkg/                # 可对外共享的库代码
├── api/                # API 定义（协议、接口描述）
├── config/             # 配置文件与默认值
├── web/                # Web 静态资源（可选）
├── scripts/            # 构建/部署脚本
├── test/               # 外部集成测试
├── docs/               # 项目文档
├── Makefile            # 构建自动化
└── go.mod / go.sum     # 模块依赖管理

1.1.2 核心目录职责对比

目录	职责	导入限制	典型内容
cmd/	应用入口点，每个子目录对应一个可执行程序	可导入 internal、pkg	main.go、依赖初始化、启动服务器
internal/	业务核心逻辑、私有 handler、数据访问层	仅限本项目内部导入	service、repository、middleware
pkg/	可对外公开的通用库	无限制（外部项目可导入）	加密工具、日志封装、类型转换
api/	API 协议定义（protobuf / OpenAPI / 接口契约）	通常不包含 Go 代码	.proto、.yaml、.json
config/	配置加载逻辑与默认值	可被 cmd 和 internal 导入	YAML/TOML 文件、配置结构体

1.1.3 目录结构关系图

下图展示了各目录之间的依赖与调用关系，帮助理解数据流与模块边界：

1.1.4 各目录详细职责说明

cmd/ — 应用入口

每个子目录对应一个独立的可执行程序。例如：

cmd/
├── api-server/          # HTTP API 服务
│   └── main.go
├── cron-worker/         # 定时任务
│   └── main.go
└── migration-tool/      # 数据库迁移工具
    └── main.go

main.go 的职责仅限于：解析命令行参数、加载配置、初始化日志与数据库连接、启动服务。业务逻辑必须委托给 internal 中的模块。

internal/ — 私有业务逻辑

这是项目的核心。Go 编译器会阻止任何外部包导入 internal 及其子包。典型结构：

internal/
├── handler/             # HTTP 处理器（路由绑定）
├── service/             # 业务用例（事务编排）
├── repository/          # 数据访问（数据库/外部 API）
├── middleware/          # 中间件（鉴权、日志、限流）
└── model/               # 内部领域模型

pkg/ — 可共享库

存放可以被外部项目直接导入的代码。例如：

pkg/
├── crypto/              # 加密/解密工具
├── logger/              # 日志封装
├── validator/           # 输入校验
└── pagination/          # 分页工具

pkg 中的代码应保持高度抽象，不依赖项目内部业务模型。

api/ — 接口定义

存放 API 协议描述文件，用于前后端或微服务之间的契约对齐：

api/
├── proto/               # gRPC protobuf 定义
│   └── user/v1/
│       └── user.proto
├── openapi/             # RESTful OpenAPI 规范
│   └── user.yaml
└── graphql/             # GraphQL schema
    └── schema.graphql

config/ — 配置管理

集中管理配置加载逻辑：

config/
├── config.go            # 配置结构体定义
├── config.yaml          # 默认配置
├── config.dev.yaml      # 开发环境覆盖
└── config.prod.yaml     # 生产环境覆盖

1.1.5 目录职责速查表

目录	是否包含 Go 代码	外部可导入	典型文件数	变更频率
cmd/	是	否	1~3 个 main.go	低
internal/	是	否	20~100+	高
pkg/	是	是	5~20	中
api/	否（协议文件）	—	3~15	中
config/	是 + 配置文件	否	3~8	低

1.1.6 实战建议：如何落地标准布局

1. 从 cmd 开始：先确定项目需要几个可执行程序（API 服务、Worker、CLI 工具），为每个创建子目录。
2. 用 internal 保护核心：所有业务 handler、service、repository 都放在 internal 下，避免外部误导入。
3. pkg 只放通用组件：如果某个工具函数与业务模型强相关，应放在 internal/pkg 而非顶层 pkg。
4. api 与 internal 同步：修改 API 协议后，立即更新 internal/handler 中的实现，保持契约一致性。
5. config 独立于环境：使用 os.Getenv 或 Viper 库加载配置，避免硬编码。