3. Gin框架快速入门：Gin的安装、第一个Gin HTTP服务、路由基础（GET/POST）

Gin 是 Go 语言生态中最流行的 Web 框架之一，以极致的性能、轻量的 API 设计和强大的中间件机制著称。本章将带你从零搭建 Gin 开发环境，完成第一个 HTTP 服务，并掌握最核心的路由定义方式，为后续的契约压测打下坚实基础。

3.1 安装 Gin

Gin 的安装依赖 Go Modules 机制。确保你的 Go 版本 ≥ 1.16，并已初始化项目模块。

安装步骤

1. 创建项目目录并初始化模块：go mod init go-web-bench
2. 安装 Gin 包：go get -u github.com/gin-gonic/gin
3. 验证安装：查看 go.mod 文件，确认出现 github.com/gin-gonic/gin 依赖。

3.2 第一个 Gin HTTP 服务

以下代码创建一个监听 :8080 端口的 HTTP 服务，并返回 JSON 格式的响应。这是所有 Gin 应用的起点。

package main

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

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

    // 定义根路径 GET 请求处理函数
    r.GET("/", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{
            "message": "Hello, Gin!",
            "status":  "running",
        })
    })

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

运行 go run main.go，访问 http://localhost:8080/，你将看到：

{"message":"Hello, Gin!","status":"running"}

3.3 路由基础：GET 与 POST

Gin 的路由定义遵循 HTTP方法(路径, 处理函数) 的模式。以下表格对比了 GET 和 POST 路由的典型用法与差异。

特性	GET 路由	POST 路由
定义方式	r.GET("/path", handler)	r.POST("/path", handler)
数据来源	URL 查询参数 (c.Query())	请求体 (JSON/表单，c.ShouldBindJSON())
幂等性	是（只读，不修改资源）	否（创建/修改资源）
缓存	可被浏览器/代理缓存	通常不缓存
典型场景	查询列表、获取详情	提交表单、创建订单

3.3.1 GET 路由示例：查询参数

r.GET("/user", func(c *gin.Context) {
    name := c.DefaultQuery("name", "guest")
    age := c.Query("age")
    c.JSON(http.StatusOK, gin.H{
        "name": name,
        "age":  age,
    })
})

访问 /user?name=alice&age=30 返回：{"name":"alice","age":"30"}。

3.3.2 POST 路由示例：JSON 请求体

type LoginRequest struct {
    Username string `json:"username" binding:"required"`
    Password string `json:"password" binding:"required"`
}

r.POST("/login", func(c *gin.Context) {
    var req LoginRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }
    c.JSON(http.StatusOK, gin.H{
        "username": req.Username,
        "status":   "logged_in",
    })
})

3.4 Gin 路由处理流程（SVG）

下图展示了 Gin 从接收到 HTTP 请求到返回响应的完整路由处理流程，帮助理解中间件、路由匹配与处理函数的协作关系。

3.5 路由分组与路径参数

在实际项目中，路由通常按业务模块分组，并包含动态路径参数。Gin 提供了简洁的 API 支持这些模式。

路由分组

v1 := r.Group("/api/v1")
{
    v1.GET("/users", listUsers)
    v1.POST("/users", createUser)
    v1.GET("/users/:id", getUserByID)
}

路径参数

r.GET("/users/:id", func(c *gin.Context) {
    id := c.Param("id")
    c.JSON(http.StatusOK, gin.H{"user_id": id})
})

3.6 路由注册方式对比（SVG）

以下 SVG 图对比了 Gin 中三种常见的路由注册方式：直接注册、分组注册和带中间件的分组注册，帮助你在不同场景下做出选择。

3.7 本章小结

• Gin 安装只需 go get 一行命令，依赖 Go Modules 管理。
• 第一个 Gin 服务通过 gin.Default() + r.Run() 即可启动，默认返回 JSON。
• GET 路由使用 c.Query() 获取参数，POST 路由使用 c.ShouldBindJSON() 解析请求体。
• 路由分组和路径参数是构建 RESTful 接口的基础，也是后续契约压测中 URL 构造的核心依据。