2. Gin环境搭建：Go语言环境配置、Gin模块安装、第一个Gin Hello World程序

本章是Gin框架开发的起点。在编写任何中间件或错误处理逻辑之前，必须完成Go语言运行环境配置、Gin模块安装，并验证第一个可运行的HTTP服务。以下步骤适用于Windows、macOS和Linux三大主流操作系统。

2.1 Go语言环境配置

Gin框架基于Go 1.13及以上版本，推荐使用Go 1.21+以获得最佳模块支持和性能优化。安装过程分为下载、安装和验证三个步骤。

2.2 初始化项目与安装Gin模块

Go Modules是官方依赖管理方案，每个Gin项目都应从模块初始化开始。以下为完整操作流程：

1. 创建项目目录：mkdir gin-hello && cd gin-hello
2. 初始化模块：go mod init gin-hello（模块名可自定义，如 github.com/yourname/gin-hello）
3. 安装Gin：go get -u github.com/gin-gonic/gin
4. 验证依赖：检查 go.mod 文件是否包含 github.com/gin-gonic/gin 条目

2.3 第一个Gin Hello World程序

编写一个最简单的HTTP服务，监听 8080 端口，返回JSON格式的问候信息。这是验证环境是否正确的标准测试用例。

package main

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

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

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

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

2.4 运行与验证

在项目根目录执行以下命令启动服务：

go run main.go

终端输出示例：

[GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.
[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

使用浏览器或 curl 测试：

curl http://localhost:8080/hello
# 输出：{"message":"Hello, Gin!","status":"success"}

2.5 项目结构速览

一个最小可运行的Gin项目包含以下核心文件：

2.6 环境搭建与请求流程

下图展示了从Go环境配置到第一个Hello World请求的完整链路，包含关键组件和交互关系。

2.7 常见问题与解决方案

• 端口被占用：修改 r.Run(":8081") 或使用 r.Run(":0") 让系统分配随机端口。
• 模块下载超时：设置 GOPROXY=https://goproxy.cn,https://goproxy.io,direct 后重试。
• go.sum 校验失败：删除 go.sum 并执行 go mod tidy 重新生成。
• Windows路径空格：确保 GOPATH 路径不含空格，或使用短路径名。