Go 输入校验怎么把清洗、验证和 JSON Schema 放在一次流程里

如果一个 Go 接口既要去掉用户输入两侧的空格，又要统一邮箱大小写、检查必填字段，还要把同一份规则交给前端，最容易出现的问题是：清洗写在 handler，校验写在另一个包，Schema 又手工维护一份。更稳妥的做法是让请求结构成为规则的中心，再把处理拆成“规范化、校验、契约输出”三个边界。

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

本文使用 Golang News 近期介绍的 Checker 作为观察入口，示例和组织方式全部重新设计；技术事实以 Go 标准库与项目公开文档为准。

先把输入处理拆成三层

先明确三个动作的区别：规范化会改变输入值，例如去掉首尾空格；校验只判断值是否满足约束；契约输出则把结构上的规则转换成接口文档。它们可以共用一份字段声明，但不要混成一个无法解释的“大验证函数”。

下面的请求模型故意使用与常见注册表单不同的字段，重点是观察处理顺序：先规范化，再判断必填和格式，最后才把通过的数据交给业务层。

package main

import (
    "fmt"

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

type MemberRequest struct {
    // 先清洗昵称，再确认它不是空值。
    Nickname string `json:"nickname" checkers:"trim required min-len:2"`
    // 邮箱先统一小写，后续校验和存储使用同一种表示。
    Email string `json:"email" checkers:"trim lower required email"`
    // 两次输入必须和密码字段保持一致。
    PasswordAgain string `json:"password_again" checkers:"required eq-field:Password"`
    Password      string `json:"password" checkers:"required min-len:10"`
}

func main() {
    req := &MemberRequest{
        Nickname:      "  Lin  ",
        Email:         "  LIN@EXAMPLE.COM ",
        Password:      "long-password",
        PasswordAgain: "long-password",
    }

    // CheckStruct 会按标签处理字段，并返回结构化的错误集合。
    errs, valid := checker.CheckStruct(req)
    if !valid {
        // JSON 适合直接作为接口错误响应，避免丢失字段定位信息。
        data, err := errs.JSON()
        if err != nil {
            panic(fmt.Errorf("marshal validation errors: %w", err))
        }
        fmt.Println(string(data))
        return
    }

    // 校验通过后，req 中已经是规范化后的业务输入。
    fmt.Println(req.Nickname, req.Email)
}

这里的关键不是标签数量，而是顺序语义：trim lower required email 先把值变成可比较的形态，再执行约束。校验失败时返回结构化错误；成功时业务层拿到的就是可以继续处理的值。

错误要保留原因，别只拼接字符串

输入校验错误通常要回到 HTTP 层，而文件、数据库或外部服务错误则要继续向上返回。两者都不应该通过字符串拼接来“伪装上下文”，因为调用方可能还要使用 errors.Is 或 errors.As 判断原始原因。

var errEmailExists = errors.New("email already exists")

func saveMember(req *MemberRequest) error {
    // 示例中用哨兵错误代表持久化层返回的重复邮箱。
    if req.Email == "used@example.com" {
        return fmt.Errorf("save member: %w", errEmailExists)
    }
    return nil
}

func handle(req *MemberRequest) error {
    // 输入错误已经在边界层处理，这里只接收通过校验的结构。
    if err := saveMember(req); err != nil {
        // 使用 %w 保留底层错误，调用者仍可做精确判断。
        return fmt.Errorf("member command failed: %w", err)
    }
    return nil
}

对于请求层，验证错误应包含字段和规则；对于业务层，包装错误应加入当前动作，例如“保存会员失败”，但仍保留原始错误链。这样日志可读，代码也能做稳定分支。

让校验规则同时成为接口契约

如果前端还要知道哪些字段必填、字符串最短长度是多少，单独手写一份 JSON Schema 很快就会和 Go 结构漂移。Checker 的思路是从结构标签生成 Draft 2020-12 Schema，让前端契约和服务端校验至少共享同一组字段声明。

func schemaForMember() ([]byte, error) {
    // Schema 从同一结构类型生成，避免再维护一份平行字段清单。
    schema, err := checker.JSONSchema(MemberRequest{})
    if err != nil {
        // 生成失败时保留上下文，调用方可以决定是否阻止文档发布。
        return nil, fmt.Errorf("generate member schema: %w", err)
    }
    return schema.JSON()
}

Schema 是接口说明，不等于运行时验证本身。运行时仍要对请求执行校验；Schema 也不应被当作权限系统。尤其是跨字段规则、数据库唯一性和租户权限，往往不能只靠静态结构表达。

什么时候改用显式 Pipeline

结构标签适合字段之间相对独立、规则能随请求模型表达的场景。如果某个规则要查数据库、读取租户信息、调用上下文取消，应该把它放到显式 Pipeline，而不是把外部依赖硬塞进标签。

func checkTenant(ctx context.Context, req MemberRequest) error {
    // 外部查询需要上下文，因此不把数据库依赖写进静态标签。
    if err := ctx.Err(); err != nil {
        return fmt.Errorf("tenant check canceled: %w", err)
    }
    // 这里接入真实租户查询，并返回可定位的业务错误。
    return nil
}

可以把流程固定成：解析请求 → 标签校验与规范化 → 上下文相关检查 → 业务保存。这样每一步都有明确责任，失败时也能判断是用户输入、外部依赖还是业务状态问题。

几个容易踩坑的判断

• 清洗不是安全边界。HTML 转义、权限检查和业务白名单仍要根据输出场景单独设计。
• 原地规范化会改变请求对象。进入审计或签名流程前，先确定记录的是原始值还是规范化后的值。
• Schema 生成成功不代表每个业务规则都被覆盖，数据库唯一性和动态权限必须留在业务层。

归纳起来：把稳定的字段规则放回请求结构，把清洗和验证保持在同一条可解释链路；把错误作为错误返回；再从同一结构生成接口契约。规则需要上下文时，及时切到显式 Pipeline，边界会比继续堆标签更清楚。

相关问题

清洗应该在 JSON 反序列化前还是后？通常在得到结构化字段后处理更容易表达规则；若担心超大输入，仍应先做请求体大小和解析层面的限制。

JSON Schema 能替代服务端校验吗？不能。Schema 主要描述契约，服务端仍要在不可信输入边界执行校验和业务授权。