当前位置：首页 > 文章列表 > Golang > Go教程 > Go 请求参数怎样先归一化再统一校验

Go 请求参数怎样先归一化再统一校验

来源：17golang原创 2026-10-09 01:07:15 0浏览收藏

Go 服务最容易失控的输入处理方式，是在 HTTP 处理器里一边取字段、一边 trim、一边判断必填，最后把半清洗的数据继续传给业务层。更稳的做法是给请求建立专用结构体：先把输入整理成统一形态，再集中校验字段规则和字段之间的关系。

本文围绕一条可落地的请求边界展开：归一化只负责把数据变得可比较，校验负责判断它是否满足契约；两者完成后，业务层只接收已经处理过的输入。

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

为什么要把归一化放在校验之前

外部请求的同一个逻辑值，可能带有首尾空格、不同大小写或全角字符。如果直接校验原始值，规则结果会被输入的表现形式影响；如果先在多个处理器里手写清洗，又很容易出现 A 接口处理了空格、B 接口忘记处理的分叉。

可以把入口拆成三个明确阶段：

原始请求：只代表客户端提交了什么，不能直接作为领域对象。
归一化：执行 trim、大小写转换和默认值等确定性变换。
校验：检查必填、格式、长度、集合大小和字段关系。

Go 请求输入从原始字段经过归一化和校验后进入清洗结构体的结构图 — 图1：请求字段先归一化再校验的结构示意图，不是运行截图。

这个顺序的关键不是某个库的语法，而是让校验面对稳定输入。例如邮箱首尾的空格应该先被移除，随后再判断格式；否则“看起来相同”的值可能得到不同结果。

用专用结构体承接请求字段

下面的例子使用 Checker 的结构体标签表达入口规则。示例特意把请求结构体和领域对象分开：请求字段是客户端契约，领域对象还可以有更严格的业务不变量。

package main

import (
    "encoding/json"
    "fmt"

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

// CreateUserInput 只承接外部请求，避免把未校验的字段直接交给领域层。
type CreateUserInput struct {
    Account     string   `json:"account" checkers:"trim lower required email"`
    Secret      string   `json:"secret" checkers:"required min-len:12"`
    SecretAgain string   `json:"secret_again" checkers:"required eq-field:Secret"`
    Groups      []string `json:"groups" checkers:"@max-len:4 trim"`
}

func main() {
    input := &CreateUserInput{
        Account:     "  Dev@Example.COM ",
        Secret:      "correct-horse-battery",
        SecretAgain: "correct-horse-battery",
        Groups:      []string{" backend ", "platform"},
    }

    // CheckStruct 会按标签处理字段，并把归一化结果写回 input。
    errs, ok := checker.CheckStruct(input)
    if !ok {
        // JSON 错误适合在 HTTP 边界转换成统一响应体。
        payload, _ := errs.JSON()
        fmt.Println(string(payload))
        return
    }

    // 通过校验后，业务层拿到的是可直接比较和持久化的值。
    encoded, _ := json.Marshal(input)
    fmt.Println(string(encoded))
}

这里的重点有三个。第一，标签里的处理顺序表达了意图：账号先去空格、转小写，再判断必填和邮箱格式。第二，确认密码用字段关系规则表达，避免在多个 handler 中重复比较。第三，校验通过后继续使用同一个请求对象，可以明确它已经完成了入口清洗。

把字段规则和跨字段规则分开理解

单字段规则回答“这个值本身是否合格”，例如账号是否为空、密钥长度是否足够；跨字段规则回答“两个或多个值放在一起是否成立”，例如确认密钥必须等于原密钥。二者混在一个大函数里时，错误通常会变成一串难以定位的字符串。

对集合字段，还要区分容器规则和条目规则。容器规则限制 groups 的数量，条目规则处理每个组名的空白或字符约束。这样的拆分能让接口契约更接近真实业务边界：集合不能太大，每个成员也必须可用。

type ChangeEmailInput struct {
    // trim 先消除用户复制粘贴带来的首尾空白，再检查邮箱格式。
    NewEmail string `json:"new_email" checkers:"trim lower required email"`
    // 条件规则只在通知开关打开时要求渠道字段存在。
    Notify   bool   `json:"notify"`
    Channel  string `json:"channel" checkers:"required-if:Notify:true"`
}

// 真实项目中应把 CheckStruct 的错误集合映射为稳定的字段错误对象。
func validateChange(input *ChangeEmailInput) error {
    // 这里保留错误返回，让调用方决定 HTTP 状态码和响应格式。
    _, ok := checker.CheckStruct(input)
    if !ok {
        return fmt.Errorf("请求字段不满足契约")
    }
    return nil
}

如果业务规则需要数据库查询、租户信息或上下文，就不要硬塞进结构体标签；可以在结构体校验通过后，再使用带有 context.Context 的程序化流水线完成依赖外部状态的判断。

Go 请求结构体通过跨字段规则和条目规则分流到错误 JSON 或业务服务的关系图 — 图2：字段关系、错误集合与业务服务的结构示意图，不是运行截图。

在 HTTP 边界统一返回错误

校验库不应该决定你的业务状态码、日志字段或响应 envelope。它更适合负责产生结构化错误，HTTP handler 再把错误转换成项目统一的 JSON 格式。这样 REST 接口、消息消费者和定时任务可以共享同一套输入规则，同时保留各自的失败协议。

func createUserHandler(w http.ResponseWriter, r *http.Request) {
    var input CreateUserInput
    if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
        // JSON 语法错误与字段契约错误分开，便于客户端定位问题。
        http.Error(w, "invalid JSON", http.StatusBadRequest)
        return
    }

    // 入口只允许已归一化、已校验的数据进入服务层。
    errs, ok := checker.CheckStruct(&input)
    if !ok {
        body, _ := errs.JSON()
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(http.StatusUnprocessableEntity)
        _, _ = w.Write(body)
        return
    }

    // createUser 接收清洗后的输入，不再重复 trim 或比较确认字段。
    if err := createUser(r.Context(), input); err != nil {
        http.Error(w, "service unavailable", http.StatusServiceUnavailable)
        return
    }
    w.WriteHeader(http.StatusCreated)
}

示例中的 400 和 422 只是常见的项目约定，实际项目应保持与已有 API 契约一致。重要的是把“请求体无法解析”和“请求体可解析但不满足字段规则”分成两类，避免客户端只能看到一个含义模糊的错误。