17370845950

go-playground/validator是Go字段校验事实标准，通过struct tag声明规则，需注意嵌套字段用dive、指针校验加required、字符串非空用min=1，自定义校验函数签名必须为func(fl validator.FieldLevel) bool，并统一处理错误提示。

用 validator 包做结构体字段校验最直接

Go 原生不提供运行时字段校验机制，go-playground/validator 是事实标准。它通过 struct tag 声明规则，在 HTTP handler 中对请求体（如 json 解析后的结构体）做一次性校验。

常见错误是只校验顶层结构体，忽略嵌套字段或指针字段未解引用；还有人误以为 required 能校验空字符串——其实它只判非零值，required_with 或 min=1 才管字符串长度。

• validate:"required,min=1" 同时防 nil、空字符串、空白符
• 对指针字段加 validate:"required" 会校验指针是否为 nil；若要校验其指向值，需额外加 dive（如 *User → validate:"dive"）
• HTTP handler 中应统一在 BindJSON 后立即调用 Validate.Struct()，别等到业务逻辑中途才校验

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

func CreateUser(c *gin.Context) {
    var req CreateUserRequest
    if err := c.ShouldBindJSON(&req); err != ni
l {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    if err := validator.New().Struct(req); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    // ...
}

自定义校验函数应对业务逻辑强约束

内置规则覆盖不了「用户名不能含敏感词」「密码需包含大小写字母和数字」这类场景，必须注册自定义函数。关键点在于：函数签名必须固定，且返回 error；注册名要和 tag 中一致；注意并发安全——validator 实例通常复用，函数内别改全局状态。

• 函数签名必须是 func(fl validator.FieldLevel) bool
• 用 v.RegisterValidation("strong_pwd", strongPassword) 注册后，tag 写 validate:"strong_pwd"
• 校验失败时，fl.Error() 返回的 error 会进入最终错误列表，建议带字段名前缀便于前端定位

func strongPassword(fl validator.FieldLevel) bool {
    s := fl.Field().String()
    hasUpper := false
    hasLower := false
    hasDigit := false
    for _, r := range s {
        switch {
        case r >= 'A' && r <= 'Z':
            hasUpper = true
        case r >= 'a' && r <= 'z':
            hasLower = true
        case r >= '0' && r <= '9':
            hasDigit = true
        }
    }
    return hasUpper && hasLower && hasDigit && len(s) >= 8
}

// 注册一次即可，建议放在 init() 或 main() 开头
v := validator.New()
v.RegisterValidation("strong_pwd", strongPassword)

路径参数和查询参数校验容易被忽略

很多人只校验 POST /body，但 GET /users/:id 的 :id 或 ?page=abc 的 page 同样需要校验。Gin 的 c.Param() 和 c.Query() 返回的是字符串，不自动转类型也不校验格式。

• c.Param("id") 拿到的是字符串，需手动 strconv.ParseUint() 并检查 error
• c.Query("page") 默认返回空字符串，不是 "0"，ParseInt("", 10, 64) 会 panic
• 推荐封装一个 MustUint64(c, "id", 1) 工具函数，带默认值、范围限制和错误统一处理

func MustUint64(c *gin.Context, key string, def uint64) uint64 {
    s := c.Param(key)
    if s == "" {
        return def
    }
    v, err := strconv.ParseUint(s, 10, 64)
    if err != nil || v == 0 {
        c.AbortWithStatusJSON(400, gin.H{"error": "invalid " + key})
        return 0
    }
    return v
}

// 使用
userID := MustUint64(c, "id", 0)
if userID == 0 {
    return // 已 abort
}

校验失败时的错误提示要区分层级和语义

直接把 validator.ValidationErrors 转成 JSON 返回给前端，会导致中文乱码、字段名暴露内部结构、错误信息过于技术化（比如 Key: 'CreateUserRequest.Email' Error:Field validation for 'Email' failed on the 'email' tag）。必须做映射和裁剪。

• 用 err.(validator.ValidationErrors) 类型断言获取具体错误列表
• 遍历每个 FieldError，用 error.Translate()（配合 ut.Translator）转中文，或手动 map 字段名→中文名
• 避免返回 StructNamespace() 这种带包路径的字段标识，只取 Field() 或自定义 Tag()

真正难的不是写校验逻辑，而是让错误反馈既准确又友好——前端靠字段名绑定提示，用户需要知道「邮箱格式不对」而不是「email tag failed」；服务端日志里则要保留原始字段路径，方便排查到底是哪个嵌套结构出问题。