Gin Go Web 框架¶

一句话概述：Gin 是 Go 语言最流行的 Web 框架，性能极高（零内存分配路由），API 简洁优雅，82K+ GitHub Stars，单核可达 12 万 QPS。

核心知识点¶

概念	白话解释
Engine	引擎 = Gin 的核心实例
Context	上下文 = 封装请求和响应的对象（每个请求一个）
Middleware	中间件 = 请求处理链上的通用逻辑
RouterGroup	路由组 = 按前缀分组管理路由
Binding	绑定 = 把请求数据自动映射到 Go 结构体
Handler	处理器 = 处理具体请求的函数

安装配置¶

go mod init myapp  # 初始化 Go 模块
go get -u github.com/gin-gonic/gin  # 安装 Gin（v1.10+）

基本使用¶

// main.go
package main

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

type Sample struct {
    ID      int    `json:"id"`                          // JSON 字段映射
    Name    string `json:"name" binding:"required,min=3"` // 必填，最少3字符
    Species string `json:"species" binding:"required"`
}

func main() {
    r := gin.Default()  // 创建引擎（带 Logger 和 Recovery 中间件）

    // 路由组
    api := r.Group("/api/v1")  // /api/v1 前缀
    {
        api.GET("/samples", listSamples)       // 列出样本
        api.GET("/samples/:id", getSample)     // 获取单个样本
        api.POST("/samples", createSample)     // 创建样本
    }

    r.Run(":8080")  // 启动在 8080 端口
}

func listSamples(c *gin.Context) {
    page := c.DefaultQuery("page", "1")  // 查询参数（有默认值）
    c.JSON(http.StatusOK, gin.H{           // 返回 JSON
        "data": []Sample{},
        "page": page,
    })
}

func getSample(c *gin.Context) {
    id := c.Param("id")  // 路径参数
    c.JSON(http.StatusOK, gin.H{"id": id})
}

func createSample(c *gin.Context) {
    var sample Sample
    if err := c.ShouldBindJSON(&sample); err != nil {  // 绑定 JSON 并验证
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }
    sample.ID = 1
    c.JSON(http.StatusCreated, sample)  // 201 返回
}

中间件¶

// 自定义认证中间件
func AuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        token := c.GetHeader("Authorization")  // 获取请求头
        if token == "" {
            c.JSON(401, gin.H{"error": "未授权"})
            c.Abort()  // 中止请求
            return
        }
        c.Set("user", "admin")  // 存储数据到上下文
        c.Next()  // 继续下一个处理器
    }
}

// 使用中间件
api := r.Group("/api", AuthMiddleware())

结构化项目¶

// handlers/sample.go — 按功能分文件
type SampleHandler struct {
    db *sql.DB  // 数据库连接
}

func NewSampleHandler(db *sql.DB) *SampleHandler {
    return &SampleHandler{db: db}
}

func (h *SampleHandler) List(c *gin.Context) {
    // 使用 h.db 查询数据库
    c.JSON(200, gin.H{"data": []Sample{}})
}

// main.go 中使用
handler := NewSampleHandler(db)
api.GET("/samples", handler.List)

常见报错¶

报错信息	原因	解决方法
`binding validation failed`	请求数据验证失败	检查 binding tag 和请求数据
`404 page not found`	路由不匹配	检查路由路径和 HTTP 方法
`address already in use`	端口被占	换端口或杀占用进程

速查表¶

// === 请求数据获取 ===
c.Param("id")                     // 路径参数 /users/:id
c.Query("page")                   // 查询参数 ?page=1
c.DefaultQuery("page", "1")       // 带默认值的查询参数
c.ShouldBindJSON(&struct)         // 绑定 JSON 请求体
c.ShouldBindQuery(&struct)        // 绑定查询参数
c.GetHeader("Authorization")      // 获取请求头
c.FormFile("file")                // 获取上传文件

// === 响应 ===
c.JSON(200, data)                 // JSON 响应
c.String(200, "text")             // 文本响应
c.File("path")                    // 文件下载
c.Redirect(301, "/url")           // 重定向
c.Status(204)                     // 只返回状态码

// === 路由 ===
r.GET("/path", handler)           // GET
r.POST("/path", handler)          // POST
r.PUT("/path", handler)           // PUT
r.DELETE("/path", handler)        // DELETE
r.Group("/prefix")                // 路由组
r.Use(middleware)                 // 全局中间件

参考：Gin 文档 | 更新于 2026 年