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

1. Go 项目结构基础：标准项目布局

在 Go 生态中，虽然没有强制性的项目结构规范，但社区经过多年实践形成了被广泛认可的 Standard Go Project Layout（标准项目布局）。这一布局为大型项目提供了清晰的职责边界，是后续进行连接池调优、依赖注入和泄露检测的工程基石。本章将重点解析 cmd、internal、pkg 三个核心目录的职责划分。

1.1 标准布局概览

一个遵循标准布局的 Go 项目通常包含以下顶层目录结构：

my-go-project/
├── cmd/                  # 应用程序入口点
│   ├── server/           # 服务端主程序
│   │   └── main.go
│   └── worker/           # 后台任务主程序
│       └── main.go
├── internal/             # 私有应用代码
│   ├── config/           # 配置管理
│   ├── service/          # 业务逻辑层
│   ├── repository/       # 数据访问层
│   └── middleware/       # HTTP 中间件
├── pkg/                  # 可被外部项目引用的公共库
│   ├── database/         # 数据库连接池封装
│   ├── logger/           # 日志工具
│   └── validator/        # 数据校验器
├── api/                  # API 协议定义（protobuf / OpenAPI）
├── configs/              # 配置文件模板
├── scripts/              # 构建与部署脚本
├── test/                 # 外部集成测试
├── go.mod
└── go.sum

核心原则： cmd 只负责组装和启动，internal 保护私有实现不被外部引用，pkg 提供可复用的公共能力。三者形成清晰的依赖层级。

1.2 目录职责划分

目录	职责	可被外部引用	典型内容
`cmd/`	应用程序的入口点，每个子目录对应一个可执行文件	否	`main.go`，依赖注入组装，启动服务器
`internal/`	私有应用代码和业务逻辑，Go 编译器强制限制外部导入	否	service、repository、middleware、config
`pkg/`	可被外部项目引用的公共库代码	是	数据库连接池、日志、校验器、工具函数

1.3 核心目录深度解析

cmd/ —— 应用程序入口

cmd/ 目录下每个子目录代表一个独立的可执行程序。子目录名通常与二进制文件名一致。这里的 main.go 代码量应尽可能少，主要职责是：

解析命令行参数和环境变量
初始化配置对象
通过依赖注入（DI）组装各层组件
启动 HTTP 服务器、gRPC 服务或后台 Worker

// cmd/server/main.go
package main

import (
    "my-go-project/internal/config"
    "my-go-project/internal/service"
    "my-go-project/internal/repository"
    "my-go-project/pkg/database"
)

func main() {
    cfg := config.Load()
    dbPool := database.NewPool(cfg.Database)
    repo := repository.NewUserRepo(dbPool)
    svc := service.NewUserService(repo)
    // 启动 HTTP 服务器
    server := NewServer(svc)
    server.Listen(cfg.Server.Port)
}

  最佳实践： 不要在 cmd/ 中编写业务逻辑。它只是一个"组装车间"，将 internal 和 pkg 中的零件组合成可运行的机器。

internal/ —— 私有实现保护

internal/ 是 Go 语言层面提供的导入限制机制。任何位于 internal 目录下的包，只能被该 internal 的父级目录及其子目录中的代码导入。这为大型项目提供了模块边界保护。

config/：管理配置结构体和加载逻辑，通常从 YAML/JSON/环境变量读取
service/：业务编排层，调用 repository 获取数据，执行领域逻辑
repository/：数据访问层，封装 SQL/NoSQL 操作，管理连接池
middleware/：HTTP 中间件，如鉴权、日志、限流

pkg/ —— 公共能力复用

pkg/ 目录存放可以被外部项目直接引用的代码。这些代码应当是通用、无业务耦合的。在连接池调优场景中，pkg/database 是核心：

// pkg/database/pool.go
package database

import (
    "context"
    "database/sql"
    "time"
)

type Pool struct {
    master *sql.DB
    slaves []*sql.DB
}

func NewPool(cfg Config) *Pool {
    master, _ := sql.Open("postgres", cfg.MasterDSN)
    master.SetMaxOpenConns(cfg.MaxOpenConns)    // 最大打开连接数
    master.SetMaxIdleConns(cfg.MaxIdleConns)    // 最大空闲连接数
    master.SetConnMaxLifetime(cfg.MaxLifetime)  // 连接最大存活时间
    master.SetConnMaxIdleTime(cfg.MaxIdleTime)  // 空闲连接超时
    return &Pool{master: master}
}

1.4 标准布局的依赖关系图

下图展示了标准布局中各目录之间的依赖流向，以及连接池在架构中的位置：

1.5 连接池调优视角下的目录职责

从连接池调优的角度，各目录承担着不同的关注点：

目录	连接池相关职责	常见问题
`cmd/`	初始化连接池配置，注入到 repository	配置硬编码，未从环境变量读取
`internal/config`	定义连接池参数结构体（MaxOpenConns、MaxIdleConns 等）	参数缺失默认值，导致连接池行为不可控
`internal/repository`	使用连接池执行查询，确保连接归还	忘记调用 `rows.Close()` 导致连接泄露
`pkg/database`	封装连接池创建、健康检查、统计指标暴露	未设置 `ConnMaxLifetime` 导致连接长时间占用

常见陷阱： 将连接池初始化逻辑放在 internal/repository 中会导致多个 repository 各自创建连接池，造成资源浪费。正确的做法是将连接池统一放在 pkg/database 中，通过依赖注入传递给各 repository。

1.6 标准布局的变体与适配

对于中小型项目，可以适当简化结构：

单体项目：可以省略 cmd/ 的多子目录，只保留 cmd/app/main.go
微服务项目：每个微服务独立仓库，内部仍遵循 cmd/internal/pkg 结构
库项目：不需要 cmd/ 和 internal/，所有代码放在根目录或 pkg/ 下