2. Gin项目初始化：使用go mod创建项目、安装Gin依赖、编写第一个Hello World路由

本章是实战的起点。我们将从零开始，使用 Go 官方推荐的模块化管理工具 go mod 创建一个标准的 Gin 项目，并完成依赖安装与第一个路由的编写。这是后续所有中间件链、上下文传递和架构设计的基础设施。

2.1 项目初始化与目录结构

Go 1.16+ 版本已默认开启 GO111MODULE=on，我们直接使用 go mod init 命令创建项目模块。模块名建议使用完整的仓库路径，例如 github.com/yourname/gin-web，这有助于后续包管理和导入。

mkdir gin-web && cd gin-web
go mod init gin-web

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

module gin-web

go 1.21

推荐的项目目录结构如下表所示，这为后续中间件、控制器、模型分层做好了准备：

2.2 安装 Gin 依赖

使用 go get 命令安装 Gin 框架。Gin 目前最新的稳定版本为 v1.9.x，我们直接获取最新版：

go get -u github.com/gin-gonic/gin

安装完成后，go.mod 文件会自动更新，增加 require 块：

require (
    github.com/gin-gonic/gin v1.9.1
    // 其他间接依赖...
)

2.3 编写第一个 Hello World 路由

在 main.go 中编写最简 Gin 服务。核心步骤为：创建引擎 → 定义路由 → 启动监听。

package main

import (
    "net/http"
    "github.com/gin-gonic/gin"
)

func main() {
    // 1. 创建 Gin 引擎（默认包含 Logger 和 Recovery 中间件）
    r := gin.Default()

    // 2. 定义 GET 路由
    r.GET("/hello", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{
            "message": "Hello, Gin Web Architecture!",
        })
    })

    // 3. 启动服务，默认监听 :8080
    r.Run(":8080")
}

启动服务：

go run main.go

访问 http://localhost:8080/hello，浏览器或 curl 将返回：

{"message":"Hello, Gin Web Architecture!"}

2.4 Gin 引擎初始化流程解析

下图展示了从 gin.Default() 到请求处理的核心链路，帮助理解 Gin 的启动骨架：

2.5 关键概念：Engine 与 Context

在第一个 Hello World 中，有两个核心对象已经登场：

• gin.Engine：框架的“大脑”，负责路由注册、中间件链管理、请求分发。所有路由和中间件都挂载在 Engine 上。
• gin.Context：每次请求的“上下文”，封装了 Request、ResponseWriter、请求参数、中间件链指针等。后续章节的中间件链式调用和上下文传递都围绕 Context 展开。

2.6 验证项目完整性

完成上述步骤后，项目应包含以下三个关键文件：

1. go.mod — 模块定义
2. go.sum — 依赖校验
3. main.go — 入口代码

运行 go run main.go 后，终端输出示例：

[GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.

[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:   export GIN_MODE=release
 - using code:  gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /hello                    --> main.main.func1 (3 handlers)
[GIN-debug] [WARNING] You trusted all proxies, this is NOT safe. ...
[GIN-debug] Listening and serving HTTP on :8080

注意日志中的 (3 handlers) 表示该路由绑定了 3 个处理函数：Logger 中间件、Recovery 中间件、以及我们定义的匿名函数。这正是 Gin 中间件链的雏形。

2.7 本章小结

通过本章操作，你已经完成了 Gin 项目的初始化骨架搭建：