📚 课程目录第2章 Go项目结构基础

2. Go 项目结构基础：标准项目布局（Standard Go Project Layout）介绍

在 Go 社区中，虽然没有强制性的官方项目结构标准，但经过多年实践，Standard Go Project Layout 已成为最广泛采纳的约定。它并非由 Go 核心团队发布，而是社区总结出的“最佳实践”目录模式，尤其适用于可维护、可测试的中大型项目。

理解这一布局，是后续进行依赖注入改造和连接池生命周期管理的前提——错误的目录划分会导致循环依赖、测试困难、配置混乱。

2.1 核心目录结构总览

以下是一个典型的 Standard Go Project Layout 示例，以 order-service 项目为例：

order-service/
├── cmd/                    # 应用入口
│   └── server/
│       └── main.go
├── internal/               # 私有应用逻辑（禁止外部导入）
│   ├── handler/            # HTTP/gRPC 处理器
│   ├── service/            # 业务逻辑层
│   ├── repository/         # 数据访问层
│   ├── config/             # 配置加载
│   └── middleware/         # 中间件
├── pkg/                    # 可被外部项目导入的公共库
│   ├── logger/
│   └── validator/
├── api/                    # API 协议定义（proto、OpenAPI）
├── configs/                # 配置文件模板
├── scripts/                # 构建、部署脚本
├── test/                   # 外部集成测试
├── go.mod
└── go.sum

  关键原则： internal 目录是 Go 编译器强制的访问隔离边界——任何外部包都无法导入 internal 及其子包。这是防止架构腐化的第一道防线。

2.2 各目录职责与生命周期对应关系

目录	职责	与连接池生命周期的关系
`cmd/`	每个子目录对应一个可执行二进制入口，只做依赖组装和启动	连接池在此处创建、注入、关闭（生命周期起点与终点）
`internal/service/`	业务逻辑编排，不直接操作数据库	通过接口依赖连接池，不负责创建/销毁
`internal/repository/`	数据访问实现，执行 SQL 查询	持有连接池实例，执行查询后归还连接
`internal/config/`	加载配置（含数据库连接参数）	提供连接池初始化所需的 DSN、最大连接数等参数
`pkg/`	通用工具库（日志、校验、数据库驱动封装）	可提供连接池包装器，但不管理生命周期

2.3 依赖流向与连接池位置

在标准布局中，依赖方向是单向的：cmd → internal/service → internal/repository。连接池实例在 cmd 中初始化，通过构造函数逐层注入。

// cmd/server/main.go
func main() {
    cfg := config.Load()
    dbPool, err := pkg.NewDBPool(cfg.Database)  // 创建连接池
    if err != nil {
        log.Fatal(err)
    }
    defer dbPool.Close()                         // 生命周期结束

    repo := repository.NewOrderRepository(dbPool) // 注入
    svc := service.NewOrderService(repo)
    handler := handler.NewOrderHandler(svc)

    server := gin.Default()
    handler.RegisterRoutes(server)
    server.Run(cfg.Server.Addr)
}

实践建议： 连接池的 Close() 应放在 main() 函数的 defer 中，确保进程退出前优雅关闭所有数据库连接。不要将连接池关闭逻辑散落在业务层。

2.4 标准布局的依赖关系 SVG 图

下图展示了标准项目布局中核心目录的依赖流向，以及连接池实例的创建与注入路径：

2.5 常见反模式与避坑指南

反模式 1： 将连接池初始化放在 init() 函数中。这会导致测试时无法替换连接池，且无法控制初始化顺序。
反模式 2： 在 internal/repository 中直接调用 sql.Open()。这使 repository 承担了连接池生命周期管理职责，违反了单一职责原则。
反模式 3： 在 pkg/ 目录下放置业务逻辑。 pkg/ 应只包含通用工具，业务逻辑必须放在 internal/ 中。
反模式 4： 使用全局变量保存连接池实例。这会导致单元测试之间状态污染，无法并行测试。

架构红线： 连接池实例的生命周期必须由 cmd/ 层全权管理。任何业务层（service/repository）都不应直接调用 sql.Open() 或 dbPool.Close()。这是后续依赖注入改造的核心前提。

2.6 标准布局与连接池调优的衔接

在后续章节中，我们将基于此标准布局进行以下改造：

在 internal/config 中定义连接池参数结构体（MaxOpenConns、MaxIdleConns、ConnMaxLifetime）。
在 pkg/dbpool 中封装连接池创建函数，接收配置参数并返回 *sql.DB。
在 cmd/server/main.go 中完成连接池创建、注入、延迟关闭。
在 internal/repository 中通过接口接收连接池，专注 SQL 查询与连接归还。

这种分层结构使得连接池调优参数只需修改配置文件，无需改动业务代码，实现了配置与逻辑的完全解耦。