Go 结构体输入校验怎么把规范化和错误收集放在一次处理里

Go 接收外部 JSON 时，比较稳妥的边界做法是：先把空白、大小写等可确定的格式差异规范化，再一次检查所有字段并返回完整错误集合。这样业务层拿到的是可预测的数据，客户端也不用“修一个错、再提交一次”地来回试。

这篇文章受到 Golang News 最近分享的 Checker 项目启发，但示例只使用 Go 标准库重新组织思路，不复制项目的标题、实现或代码。项目官方地址：https://github.com/cinar/checker

先把输入边界固定下来

规范化不是把所有值都“改成看起来正确”。适合自动处理的是没有业务歧义的格式动作，例如去掉用户名两端空白、把邮箱域名统一为小写；金额、权限和状态这类字段不应该偷偷替用户改变。解析 JSON 后，先得到一个可修改的请求对象，再把它送入验证函数，边界会比较清楚。

package main

import (
    "errors"
    "fmt"
    "net/mail"
    "strings"
)

// SignupInput 是接口边界对象；字段值仍可能来自不可信请求。
type SignupInput struct {
    Username string `json:"username"`
    Email    string `json:"email"`
    Quantity int    `json:"quantity"`
}

// FieldError 保留字段名和用户可读原因，便于接口统一返回。
type FieldError struct {
    Field string
    Msg   string
}

// normalize 只做没有业务歧义的清理，不替用户猜测业务值。
func (in *SignupInput) normalize() {
    in.Username = strings.TrimSpace(in.Username)
    in.Email = strings.ToLower(strings.TrimSpace(in.Email))
}

// validate 继续检查全部字段，避免首个错误遮住后续错误。
func (in SignupInput) validate() []FieldError {
    var errs []FieldError
    if in.Username == "" {
        errs = append(errs, FieldError{"username", "不能为空"})
    }
    if _, err := mail.ParseAddress(in.Email); err != nil {
        errs = append(errs, FieldError{"email", "格式不正确"})
    }
    if in.Quantity  20 {
        errs = append(errs, FieldError{"quantity", "必须在 1 到 20 之间"})
    }
    return errs
}

func check(in *SignupInput) error {
    // 先修改边界对象，再把全部字段错误一次性交给调用方。
    in.normalize()
    fieldErrs := in.validate()
    if len(fieldErrs) == 0 {
        return nil
    }
    return errors.New(fmt.Sprintf("输入包含 %d 个字段错误", len(fieldErrs)))
}

上例故意让 check 只返回一个总错误，生产接口通常还会把 []FieldError 序列化为字段到消息的映射。关键点不在错误字符串，而在“规范化只做确定动作、校验不提前退出”这两个约束。

一次处理收集全部字段错误

如果只返回第一个错误，调用者很难一次修完表单。验证函数应当为每个字段追加独立结果，最后再由 HTTP 层转换为稳定的响应结构。字段顺序可以固定，方便测试和前端展示；不要把原始输入值直接拼进错误消息，以免把敏感信息写入日志。

type ValidationError struct {
    Fields []FieldError
}

// Error 只描述错误数量，详细字段信息由 Fields 单独编码。
func (e ValidationError) Error() string {
    return fmt.Sprintf("有 %d 个字段需要修正", len(e.Fields))
}

func validateInput(in *SignupInput) error {
    // 规范化必须发生在校验之前，避免同一值出现两套判断结果。
    in.normalize()
    fields := in.validate()
    if len(fields) > 0 {
        return ValidationError{Fields: fields}
    }
    return nil
}

在处理器里可以用类型断言取回字段列表，再编码成 {"errors":[...]}。如果项目需要兼容被包装过的错误，可用 errors.As；使用 Go 1.26 及以上时，也可以用 errors.AsType 得到具体错误类型，官方文档说明它会沿着错误树查找匹配类型。

什么时候值得生成 JSON Schema

JSON Schema 适合“同一套约束要被多个消费者理解”的场景，例如前端表单、接口文档和网关检查都需要知道字段类型、必填关系或长度范围。它解决的是约束描述共享，不会替代服务端最后一次校验；服务端仍要把请求当作不可信输入。

如果规则只服务一个内部函数，直接保留 Go 代码通常更简单。若要生成 Schema，应把字段标签、规范化策略和校验规则视作同一份契约的不同表达，避免 Schema 说“可为空”而服务端又把空字符串判成错误。

落地时记住这四个判断

• 能无歧义自动清理的格式动作放在规范化阶段，不能猜的业务值留给校验阶段。
• 验证函数收集全部字段错误，响应层再决定 JSON 形状；不要让业务处理器到处拼字符串。
• 错误类型需要跨层传递时，用 errors.As 或 errors.AsType，不要依赖错误文本比较。
• 只有多个消费者共享约束时才引入 JSON Schema，且 Schema 不能替代服务端校验。

常见问题

规范化应该直接覆盖原始结构体吗？ 如果结构体只存在于当前请求边界且后续不需要原文，可以覆盖；若要审计或重放，保留原始副本，把规范化结果交给业务层更安全。

为什么不在遇到错误时立即返回？ 单个字段校验可以提前结束，但接口级输入校验通常更适合收集全部字段问题，减少客户端往返次数。