Go Decoder 为什么未知字段没有报错

Go 的 encoding/json 在把 JSON 解码到结构体时，默认会忽略没有对应结构体字段的 key，所以 Decoder 遇到未知字段不报错是正常行为，不是解码器失效。需要把接口契约收紧时，必须显式调用 DisallowUnknownFields()。

排查这类问题可以先看三件事：目标是不是结构体、字段是否为导出字段、JSON 名称是否真的没有被 json 标签或大小写匹配命中。确认边界后，再决定是否启用严格模式。

默认忽略未知字段，是兼容性选择

例如目标结构体只有 name，但请求中多了 debug。默认解码仍会成功，因为未知 key 没有对应的非忽略导出字段，解码器直接跳过它。这样做适合服务端兼容客户端新增字段，也能让同一份 JSON 在不同版本结构体之间平滑传递。

package main

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

type Profile struct {
    Name string `json:"name"`
}

func main() {
    // debug 不在 Profile 中，默认模式会忽略它并继续填写 Name。
    input := `{"name":"Lin","debug":true}`
    var profile Profile
    err := json.NewDecoder(strings.NewReader(input)).Decode(&profile)
    if err != nil {
        // 语法错误或类型错误仍然需要按错误处理，未知字段不是这里的错误。
        fmt.Println("decode error:", err)
        return
    }
    fmt.Printf("name=%s\n", profile.Name)
}

先确认它真的属于“未知字段”

很多误判来自目标类型或字段声明。encoding/json 解码到结构体时会优先匹配精确名称，也接受不区分大小写的匹配；json:"user_name" 则把 JSON 名称绑定到标签指定的名字。未导出的字段即使写了同名 JSON key，也不会被填充。

如果目标是 map[string]any、map[string]json.RawMessage 或接口值，就不存在“结构体中没有该字段”的判断，所有对象 key 都可以作为 map 的键保存。此时看到“未知字段没有报错”，往往是因为选择了本来就能容纳扩展字段的目标类型。

type Request struct {
    UserName string `json:"user_name"`
    // privateID 未导出，JSON 中的 private_id 不会写入这里。
    privateID string `json:"private_id"`
}

func decodeRequest(input string) (Request, error) {
    // 标签决定外部 JSON 名称；字段名大小写变化不能替代错误的标签拼写。
    var req Request
    err := json.NewDecoder(strings.NewReader(input)).Decode(&req)
    return req, err
}

需要契约校验时显式开启严格模式

在创建、更新等对请求字段较敏感的 API 入口，可以在第一次 Decode 前调用 DisallowUnknownFields()。官方定义是：目标为结构体且输入包含与目标中非忽略导出字段都不匹配的对象 key 时，Decoder 返回错误。

func decodeStrict(input string) (Profile, error) {
    var profile Profile
    dec := json.NewDecoder(strings.NewReader(input))
    // 严格模式必须在 Decode 前设置，未知 key 才会变成解码错误。
    dec.DisallowUnknownFields()
    if err := dec.Decode(&profile); err != nil {
        // 生产接口可把该错误转换为带字段提示的 4xx 响应。
        return Profile{}, fmt.Errorf("request fields are invalid: %w", err)
    }
    return profile, nil
}

严格与宽松怎么选

严格模式只改变未知字段的处理，不会替代 JSON 语法和类型错误处理。对于可选扩展，既可以把扩展区单独设计为 map[string]json.RawMessage，也可以在边界层先做宽松接收，再将核心字段复制到内部严格结构体。

常见追问

调用了 DisallowUnknownFields 仍然不报错，可能是什么原因？

优先检查它是否真的作用在当前执行的那个 Decoder 上，以及目标是否为结构体。若代码后来改成了 json.Unmarshal、map[string]any 或自定义 UnmarshalJSON，原来的严格设置就不会自动生效。

未知字段被忽略后还能找回来吗？

如果目标只是普通结构体，默认解码完成后通常没有未知字段集合可供读取。需要记录或转发它们时，应在入口保留原始 JSON，或先解码到 map[string]json.RawMessage，再按允许字段拆分处理。

记住一句话：Decoder 的默认策略偏向兼容，DisallowUnknownFields() 才是显式的未知字段拒绝开关；真正的修复点是先确定请求契约，再选择对应的目标类型和解码策略。