Go encoding/json.Decoder 怎样拒绝请求里的多余字段

我在给 HTTP 接口收紧请求模型时，最容易忽略的一点是：Go 的 encoding/json 默认会忽略结构体中不存在的字段。客户端把 fristName 写错成拼写错误时，服务端仍可能得到一个看似正常的请求对象。

如果这个接口希望“请求里出现未声明字段就失败”，应把解析入口换成 json.NewDecoder，紧接着调用 DisallowUnknownFields，再执行 Decode。它只作用于解码到结构体的对象字段，不是一个覆盖所有 JSON 校验规则的通用器。

官方参考：https://pkg.go.dev/encoding/json#Decoder.DisallowUnknownFields

默认宽松解码为什么会放过多余字段

假设请求模型只有 name 和 quantity，但调用方发送了 quanity。普通 Decode 会把能匹配的字段写入结构体，并忽略没有对应导出字段的对象键。短期看接口兼容性较好，长期却会让拼写错误、客户端版本错配和无效配置悄悄进入业务边界。

严格模式的价值不是“让 JSON 更安全”这么笼统，而是把字段契约前移：在进入业务处理前，就能明确告诉调用方哪个字段不属于当前请求模型。下面的图只展示组件和边界关系，是静态说明图，不是运行截图。

把字段边界放在 Decoder 入口

下面的写法适合接收一个 JSON 对象并解码为 CreateOrder。关键点是先配置 Decoder，再调用 Decode；如果反过来调用，当前这次解码已经使用了默认的宽松规则。

package main

import (
    "encoding/json"
    "net/http"
)

type CreateOrder struct {
    Name     string `json:"name"`
    Quantity int    `json:"quantity"`
}

func createOrder(w http.ResponseWriter, r *http.Request) {
    var req CreateOrder
    decoder := json.NewDecoder(r.Body)
    // 先拒绝结构体中没有声明的 JSON 字段，避免拼写错误进入业务层。
    decoder.DisallowUnknownFields()
    // Decode 负责把请求对象写入已声明的字段；错误应停在 HTTP 边界。
    if err := decoder.Decode(&req); err != nil {
        http.Error(w, "请求字段不符合接口定义", http.StatusBadRequest)
        return
    }
    // 这里才进入业务处理，req 只包含模型声明的字段。
    w.WriteHeader(http.StatusCreated)
}

例如请求中出现 quanity 时，Decoder 会返回未知字段错误，Handler 直接返回 400。错误消息可以记录在服务端日志中，但对外响应通常应保持稳定，不要把内部结构体名称、文件路径或堆栈直接返回给客户端。

把解析错误转换为边界响应

工程上不要把所有 Decode 错误都当成业务失败。未知字段、字段类型不匹配、JSON 语法错误和请求体结束，分别代表不同的解析边界。未知字段错误没有一个专门的公开错误类型；对外统一返回 400 通常比依赖错误文本做复杂分支更稳妥。

如果接口只允许一个 JSON 对象，还要留意“第一次 Decode 成功但请求体后面还有内容”的情况。第二次 Decode 读到 io.EOF，才说明没有第二个 JSON 值；如果读到了另一个值或其他错误，应继续按坏请求处理。

import (
    "encoding/json"
    "errors"
    "io"
)

func decodeOne(decoder *json.Decoder, dst any) error {
    // 第一次 Decode 处理主体对象，并同时启用未知字段拒绝策略。
    decoder.DisallowUnknownFields()
    if err := decoder.Decode(dst); err != nil {
        return err
    }
    var extra any
    // 第二次 Decode 只用于确认请求体没有拼接第二个 JSON 值。
    err := decoder.Decode(&extra)
    if errors.Is(err, io.EOF) {
        return nil
    }
    if err == nil {
        return errors.New("请求体包含多个 JSON 值")
    }
    return err
}

严格模式的兼容取舍

严格模式最适合由服务端控制请求模型的写入接口、内部 RPC 或需要尽早暴露契约错误的配置入口。对外部生态开放、允许客户端携带未来字段的接口，则要先确认“未知字段”是否本来就是兼容策略的一部分；否则升级客户端时可能被旧服务端拒绝。

我通常把策略固定在接口级别：稳定的命令式请求使用 DisallowUnknownFields，确实需要扩展字段的接口继续宽松解码，但在业务层显式校验关键字段。两种模式不要在同一个接口里随意切换，否则调用方很难判断哪些字段属于协议、哪些只是被静默忽略。

常见问题

DisallowUnknownFields 会检查 JSON 数组里的每个对象吗？

当数组被解码到结构体切片时，数组元素中的对象也会按结构体字段匹配；但它不会替代业务校验，也不会自动检查字段值是否满足长度、范围或跨字段约束。

只用 json.Unmarshal 能拒绝多余字段吗？

这个方法属于 Decoder，常见做法是把输入包装成 Reader 后使用 Decoder。若继续直接调用普通 json.Unmarshal，默认仍会忽略结构体没有对应字段的 JSON 键。

一句话总结：需要拒绝请求多余字段时，把 DisallowUnknownFields 放在第一次 Decode 之前；需要单对象边界时，再用第二次 Decode 确认 io.EOF，最后在 HTTP 层把解析错误稳定地收敛为 400。