2、Gin框架快速入门：Gin的安装与Hello World、路由基础（GET/POST/PUT/DELETE）、请求与响应处理

本章是进入 Go Web 服务架构实战的第一道门槛。Gin 是目前 Go 生态中最流行的 HTTP 框架，以极致的性能、简洁的 API 和强大的中间件机制著称。我们将从零开始搭建 Gin 环境，完成经典的 Hello World，并系统掌握路由定义、请求参数读取与响应构造。

2.1 环境准备与 Gin 安装

Gin 要求 Go 1.13 及以上版本。确保已正确设置 GOPATH 或启用 Go Modules。

创建项目目录并初始化模块：

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

安装 Gin 核心库：

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

安装完成后，go.mod 文件中会自动添加 Gin 及其依赖的版本记录。验证安装是否成功：

package main

import "github.com/gin-gonic/gin"

func main() {
    r := gin.Default()
    r.GET("/ping", func(c *gin.Context) {
        c.JSON(200, gin.H{"message": "pong"})
    })
    r.Run() // 默认监听 0.0.0.0:8080
}

运行 go run main.go，访问 http://localhost:8080/ping，应返回 {"message":"pong"}。

2.2 Hello World 与 Gin 核心对象

Gin 的入口是 gin.Engine 实例。通过 gin.Default() 创建时已自带 Logger 和 Recovery 中间件。下面是最简 Hello World 结构：

package main

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

func main() {
    // 创建路由引擎
    router := gin.Default()

    // 注册路由
    router.GET("/hello", func(c *gin.Context) {
        c.String(http.StatusOK, "Hello, World!")
    })

    // 启动服务（默认 0.0.0.0:8080）
    router.Run(":8080")
}

2.3 路由基础：GET/POST/PUT/DELETE

Gin 支持 RESTful 风格的路由注册，每种 HTTP 方法都有对应的快捷函数。下表列出最常用的四种方法及其语义：

完整示例——一个简单的用户资源 CRUD 路由组：

package main

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

func main() {
    r := gin.Default()

    // 查询用户列表
    r.GET("/users", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{"method": "GET", "resource": "users"})
    })

    // 创建用户
    r.POST("/users", func(c *gin.Context) {
        c.JSON(http.StatusCreated, gin.H{"method": "POST", "resource": "users"})
    })

    // 更新用户（全量）
    r.PUT("/users/:id", func(c *gin.Context) {
        id := c.Param("id")
        c.JSON(http.StatusOK, gin.H{"method": "PUT", "id": id})
    })

    // 删除用户
    r.DELETE("/users/:id", func(c *gin.Context) {
        id := c.Param("id")
        c.JSON(http.StatusOK, gin.H{"method": "DELETE", "id": id})
    })

    r.Run(":8080")
}

2.4 请求处理：参数绑定与校验

Gin 提供了三种主要的请求参数读取方式：

• 路径参数：c.Param("name")，对应路由中的 :name
• 查询参数：c.Query("key")，对应 URL 中 ?key=value
• 请求体绑定：c.ShouldBindJSON(&struct)，自动将 JSON 请求体映射到结构体

推荐使用结构体绑定，配合 Gin 的校验标签（binding tag）实现参数校验：

type CreateUserRequest struct {
    Name  string `json:"name" binding:"required,min=2,max=20"`
    Email string `json:"email" binding:"required,email"`
    Age   int    `json:"age" binding:"gte=0,lte=150"`
}

func CreateUser(c *gin.Context) {
    var req CreateUserRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        // 校验失败，返回 400 及错误详情
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }
    // 校验通过，处理业务逻辑
    c.JSON(http.StatusCreated, gin.H{
        "name":  req.Name,
        "email": req.Email,
        "age":   req.Age,
    })
}

2.5 响应处理：JSON、XML、String 与状态码

Gin 支持多种响应格式，最常用的是 JSON。下表列出常见响应方法：

统一响应结构示例——封装成功与错误响应：

// 成功响应
func Success(c *gin.Context, data interface{}) {
    c.JSON(http.StatusOK, gin.H{
        "code":    0,
        "message": "success",
        "data":    data,
    })
}

// 错误响应
func Error(c *gin.Context, httpCode int, message string) {
    c.JSON(httpCode, gin.H{
        "code":    httpCode,
        "message": message,
        "data":    nil,
    })
}

// 使用
func GetUser(c *gin.Context) {
    // 模拟查询
    user := gin.H{"id": 1, "name": "Alice"}
    Success(c, user)
}

2.6 请求与响应生命周期 SVG 图

下图展示了一个典型 Gin 请求从进入路由到返回响应的完整流程：

2.7 路由分组与路径参数 SVG 图

Gin 支持路由分组（Group）来组织相同前缀的接口，配合路径参数实现 RESTful 资源定位：

2.8 常见问题与避坑指南

2.9 本章小结