Go JSON解析如何拒绝未知字段

我们在Go中处理JSON解析逻辑时，如果希望遇到请求里结构体未定义的未知字段就直接抛出错误拒绝解析，最方便的方式就是通过标准库json包的DisallowUnknownFields配置来实现，不用额外引入第三方依赖。

当解析来源不可信的外部JSON输入时，开启未知字段拦截可以避免字段名拼写错误、多余参数被静默忽略，减少线上隐藏bug。

如果 Go 接口把 JSON 解码到结构体时，客户端多传了一个拼写错误的字段，默认情况下它可能不会报错：encoding/json 会把目标结构体中没有对应字段的键忽略掉。需要严格拒绝时，关键做法是改用 json.Decoder，在第一次 Decode 前调用 DisallowUnknownFields()。

严格模式的核心只有一句：把 JSON 解码到结构体前启用 Decoder.DisallowUnknownFields。生产 HTTP handler 还应同时限制请求体大小、关闭 Body，并检查是否存在第二段 JSON。

为什么普通 JSON 解码会放过多余字段

例如服务端只声明了 name 和 age，客户端却发送了 nickname。普通的 json.Unmarshal 或未开启严格模式的 Decoder，重点是把能够匹配的字段填入目标值，不会把每一个额外键都当成错误。

这种宽松行为适合需要向后兼容的输入，但也会掩盖字段拼写错误。调用方以为传入了 user_name，服务端结构体实际只认 username，请求仍然可能进入业务层，最后表现成“参数没有生效”。

DisallowUnknownFields 的范围也要看清：当目标是结构体时，它会让不匹配任何非忽略、可导出字段的对象键触发错误；如果目标本来就是 map[string]any，那些键就是 map 的数据，不属于“未知字段”。

在 Decoder 上启用未知字段检查

最小改动是把解码器配置放在 Decode 之前。下面的函数把未知字段错误直接返回给 handler，上层再统一转换成 400 响应。

package main

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

type createUserRequest struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

func decodeCreateUser(r *http.Request) (createUserRequest, error) {
    var input createUserRequest

    // 先配置 Decoder，再读取第一个 JSON 对象，未知字段才会进入错误分支。
    decoder := json.NewDecoder(r.Body)
    decoder.DisallowUnknownFields()
    if err := decoder.Decode(&input); err != nil {
        return createUserRequest{}, fmt.Errorf("decode request JSON: %w", err)
    }

    // 第二次读取必须到达 EOF，避免一个请求体拼接两段 JSON。
    var extra any
    if err := decoder.Decode(&extra); err != io.EOF {
        if err == nil {
            return createUserRequest{}, fmt.Errorf("request contains trailing JSON")
        }
        return createUserRequest{}, fmt.Errorf("decode trailing JSON: %w", err)
    }
    return input, nil
}

func handler(w http.ResponseWriter, r *http.Request) {
    // 先限制输入大小，避免把无限大的请求体直接交给 JSON 解码器。
    r.Body = http.MaxBytesReader(w, r.Body, 1

这里有三个容易遗漏的点。第一，DisallowUnknownFields 必须在 Decode 之前调用；第二，MaxBytesReader 是请求体边界，不是字段校验；第三，第二次 Decode 到达 io.EOF 才能说明对象后面没有另一段 JSON。

把 HTTP 请求体边界放在解码前

严格字段检查只解决“键是否被结构体认识”，并不限制请求体总大小。接口入口可以先用 http.MaxBytesReader 包住原始 Body，再创建 Decoder。这样大小策略、字段策略和资源关闭各有清晰职责。

如果请求体超过限制，后续读取会返回错误；如果 JSON 有语法错误或类型不匹配，第一次 Decode 也会失败；如果对象之后还有第二个完整 JSON 值，第二次读取不会得到 io.EOF。这些情况都应在进入业务逻辑前结束请求。

字段名、必填项和兼容性不要混为一谈

未知字段检查不等于完整的请求参数校验，至少要区分下面几类问题：

例如 Age int 没有办法单凭零值判断客户端是传了 0，还是完全没有传 age。若业务必须区分两者，可以使用 *int，再在解码成功后检查指针是否为 nil。这属于业务输入校验，不应塞进未知字段开关里。

什么时候不建议直接开启严格模式

如果接口的协议允许客户端携带未来版本字段，或者服务端明确采用“忽略不认识扩展”的兼容策略，直接全局开启严格模式可能让新客户端无法调用旧服务。更稳妥的做法是按接口边界选择：内部管理接口、配置文件和强契约写入接口更适合严格模式；面向多版本客户端的公共接口，则应先约定版本或扩展字段的容器。

不要为了绕过错误把目标结构体改成 map[string]any。这样虽然能接受任意键，但也放弃了字段类型和拼写约束。若确实需要动态字段，可以把固定字段和扩展字段分开建模，并明确扩展字段的命名空间。

落地前的排查清单

• 目标是结构体，而不是为了接收任意键的 map。
• 在第一次 Decode 前调用 DisallowUnknownFields。
• 在 JSON 解码前设置请求体大小上限。
• handler 结束前关闭 r.Body。
• 第二次读取确认没有尾随 JSON。
• 把未知字段、类型错误和必填项缺失分别转换为可理解的客户端错误。
• 确认严格策略不会破坏既有客户端的版本兼容约定。

常见问题

DisallowUnknownFields 能检查 JSON 中缺少的字段吗？

不能。它只针对“出现了但目标结构体不认识”的字段。缺少字段仍要在解码后单独校验，指针字段可以帮助区分缺失和零值。

把 JSON 解码到 map 后还能拒绝未知字段吗？

不能按结构体字段的语义拒绝，因为 map 的设计就是接收动态键。要使用未知字段检查，应把输入映射到有明确字段集合的结构体。

为什么只调用一次 Decode 不够？

一次 Decode 只消费第一个 JSON 值。若请求体后面还拼接了第二个值，第一次可能已经成功，所以生产入口可以再 Decode 一次并要求得到 io.EOF。

最终可以把这条规则记成一组职责：MaxBytesReader 控制体积，DisallowUnknownFields 控制对象字段集合，业务校验控制必填项与取值范围，第二次 Decode 控制尾随数据，而 Close 负责请求体生命周期。把它们放在同一个入口，才能让“拒绝未知字段”真正成为可维护的接口契约。