参数校验 gvalid：v 标签与自定义规则

结论：校验统一走 gvalid：结构体字段写 v 标签（规则|规则:参数#提示语），r.Parse 或 g.Validator() 自动执行；内置规则覆盖必填/长度/范围/格式等，特殊业务规则通过 RegisterRule 扩展。

一、常用内置规则

规则	含义
required	必填
length:6,16 / min-length / max-length	长度区间/上下限
between:1,100 / min / max	数值范围
in:a,b / not-in:a,b	枚举匹配
email / phone / integer / float / boolean	类型与格式
date / datetime / date-format:Y-m-d	日期格式
json / regex:...	复杂格式
same:field / different:field	字段间比较

二、两种使用方式

• 结构体标签自动校验：r.Parse 或规范路由解析时自动触发。
• 手动校验：g.Validator() 链式调用，适合无结构体的单值校验。
• 自定义规则：gvalid.RegisterRule 注册后即可在 v 标签中使用，如 v:"idNumber"。

代码示例

type UserReq struct {
    Name string `v:"required|length:2,20#请输入姓名|姓名长度2到20"`
    Age  int    `v:"between:1,150#年龄不合法"`
    Mail string `v:"email#邮箱格式错误"`
}

// 方式一：解析即校验
if err := r.Parse(&req); err != nil {
    g.Log().Error(ctx, err.FirstError())
}

// 方式二：独立校验
err := g.Validator().Data(&req).Run(ctx)

// 方式三：自定义规则
gvalid.RegisterRule("idNumber", func(ctx context.Context, in gvalid.RuleFuncInput) error {
    if len(in.Value.String()) != 18 {
        return gerror.New("身份证号不合法")
    }
    return nil
})
// 字段写法：IdCard string `v:"idNumber"`

常见追问 / 记忆点

• 追问：校验失败的错误对象是什么？→ gvalid.Error：Map() 按字段返回错误集、FirstError() 取第一条、String() 转文本。
• 追问：规则多了性能怎么办？→ 内置规则为纯 Go 实现，无第三方依赖；确有需要可 bail 规则短路（以官方文档为准）。
• 记忆点：v 管校验、p 管参数名映射；规则用 | 串联，提示用 # 对齐；“required 在前，格式在后”。