Go encoding/json.Decoder.DisallowUnknownFields 如何拦截多余字段：API 入参校验

线上接口最难排的一类入参问题，不是 JSON 语法错，而是客户端把字段名拼错后服务端悄悄忽略了它。比如客户端发来 emial，Go 结构体只有 email，默认解码仍可能得到一个看似正常的请求对象。把解码入口换成 json.Decoder.DisallowUnknownFields，就能让这类问题在进入业务层之前暴露出来。

对需要严格收口的 JSON 请求，先用 Decoder 解码，再调用 DisallowUnknownFields，把多余字段变成明确的 400 错误；同时保留语法错误、类型错误和业务校验的分层处理。

一个拼写错误，为什么会变成“请求成功”

假设订单服务只接受收件人邮箱和备注，结构体定义如下：

type CreateOrderRequest struct {
    Email string `json:"email"`
    Note  string `json:"note"`
}

客户端把 email 写成 emial 时，默认的 JSON 解码不会因为这个对象键找不到目标字段而报错。Email 保持空字符串，后续业务代码才可能在更晚的位置发现问题；如果校验不完整，甚至会把空值写进数据库。

这里先别急着给每个字段都加一层补丁。更稳的边界是把“请求字段是否属于协议”交给解码器，把“字段值是否满足业务规则”留给后面的校验函数。

在 Decode 之前收紧 JSON 字段边界

下面的最小处理函数把严格模式放在请求进入业务层之前。示例只返回错误类型，不把原始请求体直接写入日志。

func decodeCreateOrder(r *http.Request) (CreateOrderRequest, error) {
    var req CreateOrderRequest
    dec := json.NewDecoder(r.Body)
    dec.DisallowUnknownFields()

    if err := dec.Decode(&req); err != nil {
        return CreateOrderRequest{}, err
    }
    return req, nil
}

这条链路的关键关系是：Decode 读取 JSON 对象，DisallowUnknownFields 改变解码时的字段处理策略；当对象键无法匹配 CreateOrderRequest 时，错误会在 Decode 返回。

图：未知字段在 Decode 阶段被拦截，业务处理不会收到半解析请求。

把错误转换成客户端能修复的 400

HTTP 层可以把解码错误转换成统一响应。对外可以保留 json: unknown field 这类可操作提示；对内日志则记录请求路由和错误分类，避免把完整请求体写进日志。

func createOrderHandler(w http.ResponseWriter, r *http.Request) {
    req, err := decodeCreateOrder(r)
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }
    // 这里才进入业务校验与创建订单。
    _ = req
    w.WriteHeader(http.StatusCreated)
}

如果请求中含有 emial，处理会在 decodeCreateOrder 返回错误，createOrderHandler 直接结束；只有字段边界通过后，才会继续业务校验与创建订单。

严格字段模式的边界：它不检查值，也不替你做版本治理

DisallowUnknownFields 解决的是“字段名是否属于当前结构体协议”，并不判断邮箱格式、备注长度或权限。下面这些规则仍然属于业务校验：

生产接口不宜把未知字段错误当成万能安全开关。对公开 API，新增字段前要确认旧客户端是否会发送服务端暂不认识的字段；对内部命令和配置接口，严格模式通常更值得优先开启。

日志、测试与发布前检查

最少应覆盖三种输入：合法字段、未知字段和类型错误。测试关注 HTTP 状态以及错误发生的边界，不需要把整个请求体打印出来。

func TestDecodeCreateOrderUnknownField(t *testing.T) {
    r := httptest.NewRequest(http.MethodPost, "/orders", strings.NewReader(`{"emial":"a@example.com"}`))
    _, err := decodeCreateOrder(r)
    if err == nil || !strings.Contains(err.Error(), "json: unknown field") {
        t.Fatalf("want unknown field error, got %v", err)
    }
}

图：createOrderHandler 在解码错误处返回 400，成功请求才继续业务处理。

发布前可以按这张清单复查：是否只在需要严格协议的入口启用；是否把未知字段、语法错误和业务校验分开；是否为新增字段准备兼容策略；是否用测试锁定 json: unknown field 的行为。

常见问题

DisallowUnknownFields 会检查 JSON 中的字段值吗？

不会。它主要拦截不能匹配结构体的对象键，邮箱格式、长度和权限仍需单独校验。

开启后能自动列出所有未知字段吗？

标准解码错误通常先报告一个未知字段。若接口需要一次展示多个问题，应在协议层设计额外的字段扫描逻辑，并注意不要回显敏感内容。

所有 Go API 都应该开启严格模式吗？

不一定。写入、命令和配置接口更适合严格收口；需要平滑兼容不同客户端版本的接口，应先评估新增字段策略。

把字段错误留在协议边界内

这项配置的价值不在于多写一行代码，而在于让错误尽早、稳定地落在 HTTP 解码边界。只要把 Decode 与 DisallowUnknownFields 绑定起来，再用测试确认 400 分支，客户端拼写错误就不会悄悄穿过请求层。