Checker 如何在 Go 结构体上同时完成输入清洗和规则校验

表单数据进入 Go 服务时，最容易失控的不是某一个校验规则，而是“清洗”和“校验”散落在不同函数里：邮箱还带着空格，确认密码又要单独比较，最后每个接口返回的错误格式也不一样。Checker v2 适合把这条链收回请求结构体：先按标签原地整理值，再执行字段规则和跨字段约束，失败时统一拿到结构化错误。

官方地址：https://github.com/cinar/checker/

本文围绕一个注册请求展开，重点是如何组织这条输入边界，不把库的所有检查器堆成一张清单。

先把注册请求的边界写在结构体上

安装模块后，使用 checkers 标签声明规则。trim、lower 属于原地清洗，required、email 属于校验；同一字段可以按从左到右的顺序组合。

# 添加 Checker v2 模块，版本选择交给当前项目的 Go 模块解析
go get github.com/cinar/checker/v2

package main

import (
	"fmt"

	checker "github.com/cinar/checker/v2"
)

type SignupRequest struct {
	// 先去掉两侧空白并转小写，再要求它是非空邮箱。
	Email string `json:"email" checkers:"trim lower required email"`
	// 密码只做必填和最小长度检查，避免把业务策略藏进处理函数。
	Password string `json:"password" checkers:"required min-len:8"`
	// 跨字段规则引用结构体字段名，专门处理确认密码一致性。
	ConfirmPassword string `json:"confirm_password" checkers:"required eq-field:Password"`
}

func main() {
	req := &SignupRequest{
		Email:           "  ALICE@EXAMPLE.COM  ",
		Password:        "supersecret123",
		ConfirmPassword: "supersecret123",
	}
	// CheckStruct 会在同一个请求对象上执行清洗并返回校验结果。
	errs, valid := checker.CheckStruct(req)
	if !valid {
		// JSON 方法适合直接作为接口错误体；生产代码应检查序列化错误。
		data, err := errs.JSON()
		if err != nil {
			panic(err)
		}
		fmt.Println(string(data))
		return
	}
	// 通过后，后续业务拿到的是已经整理过的值。
	fmt.Println(req.Email)
}

这个例子里，Email 的值会在检查过程中被整理为小写且去掉首尾空格。清洗发生在请求对象上，因此后续写库或生成领域对象时，不必再重复一遍相同逻辑。

把清洗和校验放进同一条链

标签的顺序不是装饰：trim required 先清掉空白，再判断是否为空；如果反过来，用户只输入空格时，必填判断可能在清洗前得到错误结论。对大小写不敏感的账号或邮箱，可以把 lower 放在格式检查前；对密码这类需要保留原样的字段，不要机械套用大小写归一化。

清洗也不是安全边界的全部。Checker 能把输入整理成更稳定的形式，但授权、业务唯一性、数据库约束和敏感字段处理仍然属于服务自己的职责。尤其是 strip-invisible 只适合用户名、检索词这类不应出现不可见控制字符的字段，不适合所有自由文本。

跨字段规则和可选字段怎么放

单字段规则描述一个值本身是否合格，例如长度、邮箱格式或数字范围；eq-field:Password 描述两个字段之间的关系。把确认密码放在结构体标签上，能让规则和输入模型一起被阅读，也方便统一生成错误信息。

type ProfileRequest struct {
	// omitempty 表示字段可以不提供；一旦提供，仍需满足 email 规则。
	Email string `json:"email" checkers:"omitempty email"`
	// 只有在字段出现时才检查 URL 格式，不把可选字段误报成必填。
	Website string `json:"website" checkers:"omitempty url"`
	// 先标准化用户名，再校验它只能由允许的字符组成。
	Username string `json:"username" checkers:"trim required alphanumeric"`
}

omitempty 的关键语义是“零值时跳过剩余规则”。因此它不适合和需要主动填充默认值的规则混用；如果字段必须由服务端补默认值，应在明确的业务层完成默认策略，再决定是否进入校验链。

错误返回给 HTTP 层时保留结构

校验失败时不要只把错误拼成一段字符串。Checker 的错误对象可以序列化为 JSON，接口层再决定状态码和响应外壳。这样前端能按字段定位提示，日志也能保留机器可读的字段名。

func validateSignup(req *SignupRequest) ([]byte, bool, error) {
	// 统一从结构体入口校验，避免每个 handler 自己拼接规则。
	errs, valid := checker.CheckStruct(req)
	if valid {
		return nil, true, nil
	}
	// 把字段级错误转换为接口可以直接嵌入的 JSON。
	data, err := errs.JSON()
	if err != nil {
		return nil, false, err
	}
	return data, false, nil
}

如果项目已经有统一的 HTTP 错误格式，可以把 errs.JSON() 的结果放进 errors 字段，而不是让校验库决定整份响应。Checker 也提供 Gin、Echo、Fiber 和 net/http 相关适配模块，但适配层应保持薄，只负责绑定请求、调用校验和写回错误。

什么时候值得生成 JSON Schema

当后端结构体同时是接口契约时，可以从同一组检查标签生成 Draft 2020-12 JSON Schema，供前端表单或接口文档使用。它的价值在于减少“后端一套规则、前端另一套规则”的漂移；如果结构体只是内部对象，就没有必要为了生成 Schema 增加流程。

落地时可以按四个问题检查边界：清洗是否只作用于允许归一化的字段；可选字段是否真的允许零值；跨字段规则是否放在输入模型而不是散落在 handler；错误响应是否仍符合现有接口契约。满足这些条件后，Checker 更像一条清晰的输入管道，而不是又一层隐藏魔法。

常见问题

Checker 会自动替业务做数据库唯一性检查吗？

不会。结构体标签适合表达输入形状和字段关系，用户名是否已存在、订单状态是否允许变更等问题必须在业务层或数据库约束中判断。

所有字符串都应该先 lower 吗？

不应该。邮箱、用户名等明确大小写策略的标识符可以归一化；密码、展示名和自由文本通常需要保留原始语义。