gin 介绍

快速入门

Gin 框架简介

安装与项目初始化

第一个 Gin 应用

Gin 与标准库对比

路由

路由基础

HTTP 方法

路由分组

路由参数

查询参数

表单参数

路由重定向

模型绑定与验证

模型绑定

JSON 绑定

XML 绑定

表单绑定

URI 绑定

参数验证

自定义验证器

绑定多个参数

响应渲染

JSON 响应

XML 响应

YAML 响应

HTML 模板渲染

静态文件服务

文件上传下载

自定义响应

中间件

中间件基础

全局中间件

路由组中间件

单路由中间件

中间件传值

日志中间件

Recovery 中间件

Context 上下文

Context 结构体

请求信息获取

Cookie 操作

设置与获取值

Context 数据存储

Context 并发安全

Context 复制

并发安全

Context 生命周期

错误处理

错误收集

错误响应

错误中间件

统一错误响应

Panic 恢复

错误处理最佳实践

高级特性

WebSocket 支持

配置管理

SSE 服务器推送

流式响应

路由组织

多路由器

Gin 运行模式

优雅关闭

Context Pool

SecureJSON

TLS/HTTPS

绑定验证器

自定义 HTTP 配置

测试

单元测试

集成测试

接口测试

测试覆盖率

测试工具函数

测试最佳实践

Mock 测试

部署与优化

构建与部署

Docker 部署

Docker 容器化

Systemd 服务

性能优化

监控与日志

生产环境配置

URI 绑定

URI 绑定可以把路径参数直接绑定到结构体，代码更清晰。

基本用法

type UserParams struct {
    ID string `uri:"id" binding:"required"`
}

r.GET("/users/:id", func(c *gin.Context) {
    var params UserParams
    if err := c.ShouldBindUri(&params); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }

    c.JSON(200, gin.H{"user_id": params.ID})
})

访问 /users/123，ID 的值是 123。

多个路径参数

type PostParams struct {
    UserID string `uri:"user_id" binding:"required"`
    PostID string `uri:"post_id" binding:"required"`
}

r.GET("/users/:user_id/posts/:post_id", func(c *gin.Context) {
    var params PostParams
    if err := c.ShouldBindUri(&params); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }

    c.JSON(200, gin.H{
        "user_id": params.UserID,
        "post_id": params.PostID,
    })
})

访问 /users/123/posts/456，得到 user_id=123 和 post_id=456。

参数验证

import "strconv"

type UserParams struct {
    ID int `uri:"id" binding:"required,gt=0"`
}

r.GET("/users/:id", func(c *gin.Context) {
    var params UserParams
    if err := c.ShouldBindUri(&params); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }

    c.JSON(200, gin.H{"user_id": params.ID})
})

访问 /users/abc 会返回错误，因为 abc 无法转换为 int。

通配符参数

type FileParams struct {
    Path string `uri:"path"`
}

r.GET("/files/*path", func(c *gin.Context) {
    var params FileParams
    if err := c.ShouldBindUri(&params); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }

    c.JSON(200, gin.H{"path": params.Path})
})

访问 /files/docs/report.pdf，Path 的值是 /docs/report.pdf。

组合绑定

URI 绑定可以和其他绑定组合使用：

type UpdateUserParams struct {
    ID   string `uri:"id" binding:"required"`
    Name string `json:"name" binding:"required"`
}

r.PUT("/users/:id", func(c *gin.Context) {
    var params UpdateUserParams
    if err := c.ShouldBindUri(&params); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }

    var body UpdateUserParams
    if err := c.ShouldBindJSON(&body); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }

    c.JSON(200, gin.H{
        "id":   params.ID,
        "name": body.Name,
    })
})

完整示例

package main

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

type UserIDParams struct {
    ID int `uri:"id" binding:"required,gt=0"`
}

type PostIDParams struct {
    UserID int `uri:"user_id" binding:"required,gt=0"`
    PostID int `uri:"post_id" binding:"required,gt=0"`
}

type FilePathParams struct {
    Path string `uri:"path"`
}

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

    r.GET("/users/:id", getUser)
    r.GET("/users/:user_id/posts/:post_id", getPost)
    r.GET("/files/*path", getFile)

    r.Run(":8080")
}

func getUser(c *gin.Context) {
    var params UserIDParams
    if err := c.ShouldBindUri(&params); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "无效的用户 ID"})
        return
    }

    c.JSON(http.StatusOK, gin.H{
        "id":   params.ID,
        "name": "User " + strconv.Itoa(params.ID),
    })
}

func getPost(c *gin.Context) {
    var params PostIDParams
    if err := c.ShouldBindUri(&params); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "无效的参数"})
        return
    }

    c.JSON(http.StatusOK, gin.H{
        "user_id": params.UserID,
        "post_id": params.PostID,
        "title":   "Post Title",
    })
}

func getFile(c *gin.Context) {
    var params FilePathParams
    if err := c.ShouldBindUri(&params); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "无效的文件路径"})
        return
    }

    c.JSON(http.StatusOK, gin.H{
        "path":    params.Path,
        "content": "文件内容",
    })
}

小结

这一章学习了：

URI 绑定的基本用法
多个路径参数
参数验证
通配符参数
组合绑定

上一章：表单绑定

下一章：参数验证