Go json.Decoder 怎么拒绝未声明字段

要拒绝 Go 结构体中没有声明的 JSON 字段，不能只用 json.Unmarshal。应创建 json.Decoder，在第一次 Decode 前调用 DisallowUnknownFields()。当输入对象包含无法匹配目标结构体导出字段或 json 标签的键时，解码器就会返回错误。

我更愿意在写入、创建订单、修改配置这类接口上启用它，因为客户端把 email 拼成 emial 时，默认的“忽略未知字段”很可能让请求看似成功，错误却被悄悄带到后续流程。

先看默认行为为什么容易漏错

假设接口只接收姓名和邮箱：

type CreateUserRequest struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

输入里多出 role，或者把 email 写成 emial，默认解码通常会忽略无法匹配的键。对于需要向后兼容、允许客户端携带扩展字段的读取场景，这种行为很方便；对于写接口，它也可能掩盖拼写错误和协议漂移。

启用严格字段匹配

最小写法只需要在 Decoder 上加一行配置：

package main

import (
    "encoding/json"
    "fmt"
    "strings"
)

type CreateUserRequest struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

func main() {
    body := `{"name":"Alice","email":"a@example.com","role":"admin"}`
    dec := json.NewDecoder(strings.NewReader(body))
    dec.DisallowUnknownFields() // 在 Decode 前开启未知字段拒绝策略

    var req CreateUserRequest
    if err := dec.Decode(&req); err != nil {
        // role 不在目标结构体中，因此这里会收到解码错误
        fmt.Println("请求格式不符合约定：", err)
        return
    }
    fmt.Printf("%+v\n", req)
}

这个开关有两个重要边界。第一，目标必须是结构体；解码到 map[string]any 时，任意键本来就是 map 的合法内容。第二，被 json:"-" 忽略的字段不算可接收字段，输入中的同名键仍不能靠它通过严格匹配。

别漏掉第二个 JSON 值

我早期封装严格解码时，只调用了一次 Decode。后来发现这只读取“下一个 JSON 值”，不等于确认请求体已经结束。例如一个对象后又跟着另一个对象，第一次解码可能已经成功。稳妥做法是再解码一次，并要求结果为 io.EOF。

func decodeStrict(r io.Reader, dst any) error {
    dec := json.NewDecoder(r)
    dec.DisallowUnknownFields() // 只接受目标结构体声明的字段

    if err := dec.Decode(dst); err != nil {
        return fmt.Errorf("解析 JSON：%w", err)
    }

    var extra any
    if err := dec.Decode(&extra); !errors.Is(err, io.EOF) {
        // 第二个值或残留的非法内容都应拒绝
        if err == nil {
            return errors.New("请求体只能包含一个 JSON 值")
        }
        return fmt.Errorf("请求体尾部无效：%w", err)
    }
    return nil
}

这段函数还保留了原始错误链，调用层可以继续用 errors.As 区分 *json.SyntaxError、*json.UnmarshalTypeError 等错误。未知字段错误本身适合转成统一的 400 响应，不建议把内部结构细节原样暴露给外部客户端。

接口中怎么落地更稳

在 HTTP 接口里，我通常把“读取限制”和“结构校验”分开：先限制请求体大小，再严格解码，最后检查必填字段和业务规则。DisallowUnknownFields 只解决未知键问题，不会自动判断空字符串、数值范围或跨字段约束。

func createUser(w http.ResponseWriter, r *http.Request) {
    // 限制请求体，避免把超大输入交给 JSON 解码器
    r.Body = http.MaxBytesReader(w, r.Body, 1

我的取舍是：对外部写接口默认严格，对配置读取和兼容性要求高的接口再明确放宽。严格模式最大的价值不是“更安全”这个泛泛结论，而是让调用方字段拼错时尽早得到清楚失败，而不是获得一个内容不完整的成功结果。

相关问题

json.Unmarshal 能直接拒绝未知字段吗？

标准的 json.Unmarshal 没有对应开关。需要改用 json.NewDecoder 并调用 DisallowUnknownFields，或者采用其他显式校验方案。

嵌套结构体里的未知字段也会被拒绝吗？

会。只要解码目标对应位置是结构体，输入对象键无法匹配其可用字段，严格模式就会返回错误；如果该位置是 map，则 map 仍可接收任意键。