Gin从入门到精通 (五)数据绑定与验证

数据绑定与验证

数据绑定是指将请求数据（如 JSON、表单、URL 参数等）绑定到 Go 语言中的结构体。Gin 提供了便捷的方法将请求中的数据映射到预定义的结构体字段上，使得开发者可以像访问结构体字段一样访问请求数据。

数据验证是对绑定到结构体上的数据进行检查，确保数据符合特定规则或格式。例如，确保邮箱字段是有效的邮箱格式、年龄字段是一个合法的数字等。

1.数据验证

1.1常见字段

Gin 支持多种常见的验证规则，验证是通过结构体字段中的 binding 标签来进行的。

常用的验证规则：

• required: 字段必须存在且不为空
• min、max:对于整数类型的字段，可以使用 min 和 max 来设置最小值和最大值
• email: 字段必须是有效的电子邮件地址

required：必填
确保字段不能为空。

Name string `json:"name" binding:"required"`

email：电子邮件格式
确保字段为有效的电子邮件格式。

Email string `json:"email" binding:"required,email"`

min, max：最小值与最大值
对于整数类型的字段，可以使用 min 和 max 来设置最小值和最大值。

Age int `json:"age" binding:"min=18,max=100"`

len：字符串长度
确保字符串的长度符合指定的范围。

Name string `json:"name" binding:"len=5"`

alpha：只包含字母
确保字段值只包含字母字符。

Code string `json:"code" binding:"alpha"`

alphanum：只包含字母和数字
确保字段值只包含字母和数字。

Username string `json:"username" binding:"alphanum"`

2.处理验证错误

在 Gin 中，数据验证错误通常会作为一个 error 被返回。你可以通过检查 ShouldBind 或 ShouldBindJSON 的返回值来捕获错误。

r.POST("/submit", func(c *gin.Context) {
    var user User

    if err := c.ShouldBindJSON(&user); err != nil {
        // 捕获并返回详细的验证错误信息
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		
		/*
		// 或者自定义错误信息
		 c.JSON(http.StatusBadRequest, gin.H{
        "error": "Validation failed: Name is required and Email must be valid",
    })
		*/
		
        return
    }

    c.JSON(http.StatusOK, gin.H{"message": "Data is valid"})
})

2.数据绑定

2.1 Uri参数绑定

在 Gin 中，ShouldBindUri 方法用于从 URL 路径中提取并绑定参数。路径中的动态参数（即 :param）会被提取并绑定到结构体的相应字段。

假设我们有以下 URL 路径：/:name/:id，我们需要将name和 id 从 URL 中提取并绑定到结构体

package main

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

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

func main() {
	route := gin.Default()
	route.GET("/:name/:id", func(c *gin.Context) {
		var user User
		if err := c.ShouldBindUri(&user); err != nil {
			c.JSON(400, gin.H{"msg": err.Error()})
			return
		}
		c.JSON(200, gin.H{"name": user.Name, "uuid": user.ID})
	})
	route.Run(":8080")
}

使用 c.ShouldBindUri() 方法从 URL 路径中提取 name和id 参数并绑定到 User 结构体。

binding:"required" 确保 id和name 参数是必填的

使用postman测试：

2.2 查询参数绑定

ShouldBindQuery 用于将 URL 查询参数（即 ?key=value）绑定到结构体的字段中。查询参数通常用于过滤或分页等操作。

package main

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

type SearchQuery struct {
	Name string `form:"name" binding:"required"`
	Age  int    `form:"age" binding:"required,min=18"`
}

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

	r.GET("/search", func(c *gin.Context) {
		var query SearchQuery
		// 使用 ShouldBindQuery 从查询字符串中绑定参数
		if err := c.ShouldBindQuery(&query); err != nil {
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			return
		}

		c.JSON(http.StatusOK, gin.H{"message": "Search successful", "query": query})
	})

	r.Run(":8080")
}

使用 c.ShouldBindQuery() 方法将 URL 中的查询参数（如 name 和 age）绑定到结构体字段。

binding:"required" 确保 name 和 age 字段必须提供，且 age 必须大于等于 18。

请求路径：

http://localhost:8080/search?name=John&age=30

返回数据：

{"message":"Search successful","query":{"Name":"John","Age":30}}

2.3 JSON 数据绑定

当客户端以 JSON 格式发送数据时，在 Gin 中可以使用 c.ShouldBindJSON 方法将 JSON 数据绑定到 Go 结构体上。

package main

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

type User struct {
	Name string `json:"name" binding:"required"` 
	Email string `json:"email" binding:"required,email"`
}

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

	r.POST("/user", func(c *gin.Context) {
		var user User

		// 绑定 JSON 数据
		if err := c.ShouldBindJSON(&user); err != nil {
			// 数据绑定失败，返回 400 错误
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			return
		}

		// 数据验证通过，返回成功响应
		c.JSON(http.StatusOK, gin.H{"message": "User created successfully", "user": user})
	})

	r.Run(":8080")
}

使用 c.ShouldBindJSON() 将请求体中的 JSON 数据绑定到 User 结构体中。

我们使用 binding:"required" 和 binding:"email" 来为 Name 和 Email 字段定义验证规则，确保 Name 必填且 Email 必须是一个有效的邮箱。

使用postman测试：

2.4 表单数据绑定

gin 通过 ShouldBind() 方法可以将 HTML 表单中的数据绑定到结构体字段上。

package main

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

type User struct {
	Name string `form:"name" binding:"required"`
	Age  int    `form:"age" binding:"required,min=18"`
}

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

	r.POST("/submit", func(c *gin.Context) {
		var user User

		// 绑定表单数据
		if err := c.ShouldBind(&user); err != nil {
			// 数据绑定失败，返回 400 错误
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			return
		}

		// 数据验证通过，返回成功响应
		c.JSON(http.StatusOK, gin.H{"message": "Form submitted successfully", "user": user})
	})

	r.Run(":8080")
}

使用 c.ShouldBind() 可以将 HTML 表单中的数据绑定到 User 结构体。

使用 binding:"required" 来确保 Name 和 Age 字段是必填项，同时用 min=18 验证 Age 字段的值必须大于等于 18。

使用postman测试：

当age值小于18时，返回结果如下：

{"error":"Key: 'User.Age' Error:Field validation for 'Age' failed on the 'min' tag"}

2.5 map参数绑定

Gin 目前没有直接支持将 URL 查询参数中的 map 形式绑定到结构体的 map 字段上。不过，可以通过自定义绑定逻辑来实现这个功能。以下是一个示例：

package main

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

// User 结构体，包含一个 map 字段
type User struct {
	UserMap map[string]string
}

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

	r.GET("/userMap/", func(ctx *gin.Context) {
		var user User
		user.UserMap = make(map[string]string)

		// 手动解析查询参数
		values, _ := url.ParseQuery(ctx.Request.URL.RawQuery)
		for key, value := range values {
			if strings.HasPrefix(key, "user[") && strings.HasSuffix(key, "]") {
				// 提取 map 的键
				start := strings.Index(key, "[") + 1
				end := strings.Index(key, "]")
				mapKey := key[start:end]
				user.UserMap[mapKey] = value[0]
			}
		}

		ctx.JSON(200, user)
	})

	r.Run(":8080")
}

在上述代码中，我们手动解析 URL 查询参数，提取出以 user[ 开头,] 结尾的键值对，并将其存储到 User 结构体的 UserMap 字段中。这样就实现了将 URL 查询参数中的 map 形式绑定到结构体的 map 字段上的功能

执行url：
http://localhost:8080/userMap?user[jay]=Beijing&user[jake]=shanghai

返回数据：

{
    "UserMap": {
        "jake": "shanghai",
        "jay": "Beijing"
    }
}

2.6 请求头绑定

ShouldBindHeader 用于将请求头中的数据绑定到结构体字段上。HTTP 请求头包含了请求的元数据，如用户代理、认证信息、内容类型等。

package main

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

type RequestHeaders struct {
	ContentType string `header:"Content-Type" binding:"required"`
	UserAgent   string `header:"User-Agent" binding:"required"`
	Name        string `header:"Name" binding:"required"`
	Email       string `header:"Email" `
}

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

	r.GET("/headers", func(c *gin.Context) {
		var headers RequestHeaders
		// 使用 ShouldBindHeader 从请求头中绑定参数
		if err := c.ShouldBindHeader(&headers); err != nil {
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			return
		}

		c.JSON(http.StatusOK, gin.H{"message": "Headers received", "headers": headers})
	})

	r.Run(":8080")
}

使用 c.ShouldBindHeader() 方法将请求头中的 Content-Type 、 User-Agent 和自定义两个字的Name 、Email数据绑定到 RequestHeaders 结构体的字段。

测试请求：

2.7 自动选择绑定方法

ShouldBind 是一个通用方法，它会根据请求的内容类型自动选择合适的绑定方法（JSON、表单、URL 参数等）。如果请求是 JSON 格式，ShouldBind 会自动调用 ShouldBindJSON；如果是表单或查询参数格式，则会调用相应的绑定方法。

package main

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

type User struct {
    Name  string `json:"name" form:"name" binding:"required"`
    Email string `json:"email" form:"email" binding:"required,email"`
}

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

    r.POST("/submit", func(c *gin.Context) {
        var user User
        // 自动选择绑定方法：JSON、表单或查询参数
        if err := c.ShouldBind(&user); err != nil {
            c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
            return
        }

        c.JSON(http.StatusOK, gin.H{"message": "Data received", "user": user})
    })

    r.Run(":8080")
}

json请求数据：

{
  "name": "clown",
  "email": "clown95@qq.com"
}

表单请求数据：

name=clown&email=clown95@qq.com

XML请求数据：

<User>
    <Name>clown</Name>
    <Email>clown95@qq.com</Email>
</User>

最终结果都成功返回数据：

 {
    "message": "Data received",
    "user": {
        "name": "clown",
        "email": "clown95@qq.com"
    }
}