📚 课程目录第1章 Go项目初始化

1. Go 项目初始化：使用 Go Module 创建项目、项目目录结构规范、引入依赖管理

本章是课程的基础起点。在开始编写业务接口和集成 CI/CD 流水线之前，必须建立一个结构清晰、依赖可控的 Go 项目。我们将从 Go Module 初始化开始，定义标准的项目目录结构，并掌握依赖管理的核心操作。

Go Module 是 Go 1.11 版本引入的官方依赖管理机制，自 Go 1.16 起成为默认行为。它通过 go.mod 文件记录项目路径和依赖版本，实现可重复构建。

创建项目目录：在本地工作区创建项目根文件夹，例如 go-api-demo。
执行 go mod init：在项目根目录运行以下命令，<module-path> 通常使用代码仓库地址（如 github.com/yourname/go-api-demo）。

mkdir go-api-demo
cd go-api-demo
go mod init github.com/yourname/go-api-demo

执行成功后，根目录下会生成 go.mod 文件，内容类似：

module github.com/yourname/go-api-demo

go 1.22

提示： go.mod 中的 go 1.22 表示项目使用的 Go 语言版本。该版本号会影响语言特性和标准库行为，建议与开发环境保持一致。

一个清晰的项目目录结构能提升代码可读性、可维护性，并方便 CI/CD 流水线按模块执行测试和构建。以下是本课程推荐的通用结构：

目录/文件	用途
`cmd/`	存放应用程序入口文件（`main.go`），按子项目拆分（如 `cmd/api/main.go`）
`internal/`	存放私有应用逻辑，不允许被外部包导入，Go 编译器会强制检查
`pkg/`	存放可被外部项目引用的公共库代码
`api/`	存放 API 定义文件（如 OpenAPI/Swagger 规范、Protocol Buffers）
`config/`	存放配置文件或配置加载逻辑
`test/`	存放集成测试、端到端测试等外部测试数据或辅助脚本
`scripts/`	存放构建、部署、数据库迁移等脚本
`docs/`	存放项目文档
`go.mod` / `go.sum`	Go Module 依赖管理文件

  关键原则：
  扁平化优先：避免过度嵌套，internal 和 pkg 下按业务模块组织包。
入口分离：cmd/ 下的每个子目录对应一个可编译的二进制文件。
私有逻辑隔离：internal 包是 Go 语言级别的访问限制，防止外部依赖侵入核心逻辑。

下图展示了本课程项目 go-api-demo 的目录结构关系：

Go Module 通过 go get 命令添加外部依赖，并自动更新 go.mod 和 go.sum 文件。go.sum 记录了每个依赖版本的哈希值，用于验证下载内容的完整性。

命令	作用
`go get <module>@<version>`	添加或更新指定版本的依赖
`go get <module>@latest`	添加或更新到最新版本
`go mod tidy`	清理未使用的依赖，并添加缺失的依赖
`go mod vendor`	将依赖复制到项目根目录的 `vendor/` 文件夹，用于离线构建
`go mod download`	下载所有依赖到本地缓存，不编译代码

本课程后续章节将使用 gin 框架构建 HTTP 接口。现在将其添加为项目依赖：

go get github.com/gin-gonic/gin@latest

执行后，go.mod 文件会新增 require 块：

module github.com/yourname/go-api-demo

go 1.22

require (
    github.com/gin-gonic/gin v1.10.0
)

注意： 不要手动编辑 go.mod 中的依赖版本号，应始终使用 go get 或 go mod edit 命令操作。手动修改可能导致 go.sum 校验失败。