快速上手

本页带你在 5 分钟内安装 govalid 并完成第一次结构体校验。

环境要求

• Go 1.16 或更高版本
• 启用 module 的项目（go.mod）

安装

go get -u github.com/wuhan005/govalid

然后在代码中引入：

import "github.com/wuhan005/govalid"

第一次校验

给需要校验的字段加上 valid 标签，并（可选地）加上 label，让错误 消息更友好：

package main

import (
    "fmt"

    "github.com/wuhan005/govalid"
)

func main() {
    form := struct {
        Name  string `valid:"required;username" label:"昵称"`
        ID    int    `valid:"required;min:0;max:999" label:"用户编号"`
        Email string `valid:"required;email"    label:"邮箱"`
    }{
        Name:  "e99_",
        ID:    1990,
        Email: "i@github.red.",
    }

    errs, ok := govalid.Check(form)
    if ok {
        fmt.Println("校验通过")
        return
    }
    for _, err := range errs {
        fmt.Println(err)
    }
}

昵称的最后一个字符不能为下划线
用户编号应小于999
邮箱不是合法的电子邮箱格式

这一切是怎么发生的？

1. Check 通过反射遍历结构体。
2. 对每个带 valid 标签的字段，每条规则（用 ; 分隔）会按顺序在 全局 Checkers 注册表中查找并执行。
3. 每条失败的规则产生一个 *ErrContext，携带字段名、标签、值和本地 化的消息——*ErrContext 自身实现了 error 接口。
4. 只有所有规则都通过时，ok 才为 true。

一条规则的结构

valid 标签是一个用 ; 分隔的规则列表。每条规则要么是：

• 单纯的校验器名：required
• 带参数的校验器：min:18、list:admin,editor,viewer

`valid:"required;min:18;max:120"`

TIP

对于格式型校验器（email、ipv4、mobile 等），空字符串会短路视 为"通过"。所以你可以用 required 控制可选/必填：

type Form struct {
    Optional string `valid:"email"`            // 允许空
    Required string `valid:"required;email"`   // 不允许空
}

字段级别的自定义错误消息

用 msg 标签可以覆盖整个字段的错误消息。第一条失败的规则会短路到 这个消息——当文案比错因细节更重要时很有用：

type Form struct {
    Password string `valid:"required;minlen:8" label:"密码" msg:"密码长度需在 8-64 之间"`
}

跨字段与业务规则

任何依赖多个字段的逻辑都属于 Validate() error 方法。govalid 会在 标签规则之后调用它：

type Form struct {
    Password       string `valid:"required;minlen:8" label:"密码"`
    RepeatPassword string `valid:"required"          label:"重复密码"`
}

func (f *Form) Validate() error {
    if f.Password != f.RepeatPassword {
        return errors.New("两次输入的密码不一致")
    }
    return nil
}

完整契约见 跨字段与业务规则。

接下来读什么？

• 核心概念 —— 规则、字段与 locale 是如何串起来的。
• 内置校验器 —— 现成规则的目录。
• 自定义校验器 —— 一行代码注册自己的校验器。
• 实战 —— 真实世界中可直接复用的示例。