结构体标签

结构体标签是 Gin 参数绑定和响应序列化的核心机制。

标签类型

标签	作用	使用场景
`json`	JSON 序列化/反序列化字段名	响应输出、JSON 请求体
`form`	Query/Form 参数字段名	URL 参数、表单数据
`binding`	参数校验规则	参数绑定校验
`uri`	URL 路径参数字段名	RESTful 路由参数
`header`	请求头字段名	Header 参数绑定

JSON 标签

控制 JSON 序列化和反序列化：

type User struct {
    ID       int    `json:"id"`              // 映射为 id
    Name     string `json:"name"`            // 映射为 name
    Password string `json:"-"`               // 忽略该字段
    Email    string `json:"email,omitempty"` // 为空时不输出
    Status   int    `json:"status,string"`   // 输出为字符串
}

r.POST("/user", func(c *gin.Context) {
    var user User
    c.ShouldBindJSON(&user)
    // 响应时 Password 字段不会出现
    // Email 为空时也不会出现
    c.JSON(200, user)
})

Form 标签

绑定 Query 或表单参数：

type Search struct {
    Keyword string `form:"keyword" binding:"required"`
    Page    int    `form:"page" binding:"min=1"`
    Limit   int    `form:"limit" binding:"max=100"`
}

// Query 参数绑定
r.GET("/search", func(c *gin.Context) {
    var search Search
    if err := c.ShouldBindQuery(&search); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    c.JSON(200, search)
})

URI 标签

绑定 URL 路径参数：

type PathParam struct {
    ID   int    `uri:"id" binding:"required"`
    Name string `uri:"name"`
}

// GET /user/123/zhangsan
r.GET("/user/:id/:name", func(c *gin.Context) {
    var param PathParam
    if err := c.ShouldBindUri(&param); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    c.JSON(200, gin.H{
        "id":   param.ID,
        "name": param.Name,
    })
})

Header 标签

绑定请求头参数：

type Headers struct {
    Token      string `header:"Authorization"`
    UserAgent  string `header:"User-Agent"`
    RequestID  string `header:"X-Request-Id"`
}

r.GET("/info", func(c *gin.Context) {
    var headers Headers
    if err := c.ShouldBindHeader(&headers); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    c.JSON(200, headers)
})

多标签组合

一个字段可以同时使用多个标签：

type Article struct {
    ID      int    `json:"id" uri:"id"`                  // JSON 和 URI 都映射为 id
    Title   string `json:"title" form:"title" binding:"required"`
    Content string `json:"content" form:"content"`
    Author  string `json:"author" form:"author" binding:"omitempty"`
}

标签命名规范

场景	推荐命名
API 响应	snake_case（如 `user_id`）
Query 参数	snake_case
请求头	保持原格式（如 `X-Request-Id`）

字段名和标签名不一致时，使用标签名进行映射；一致性原则可减少维护成本。

要点总结

json 标签控制序列化，- 表示忽略
form 标签绑定 Query/Form 参数
uri 标签绑定 URL 路径参数
binding 标签定义校验规则
多标签可组合使用，满足不同场景

📝 发现内容有误？点击此处直接编辑