Go json.Decoder.DisallowUnknownFields 为什么只拦到当前结构：嵌套对象与字段校验边界

接口配置从 JSON 解码到 Go 结构体时，最容易误判的一点是：打开 DisallowUnknownFields 并不等于所有 JSON 都会被同一种方式检查。目标字段是嵌套结构体时，未知键会继续报错；目标是 map[string]any 或经过自定义解码时，校验边界就可能停在另一层。

DisallowUnknownFields 的关键不是“递归扫描整份 JSON”，而是解码器走到一个结构体目标时拒绝无法匹配的对象键。先确认目标类型，再判断严格校验是否覆盖到了你关心的字段。

先做一个能看到边界的配置解码器

把问题缩成一个小程序更容易观察。下面的配置把固定字段放进 Database，同时保留一个用于实验性开关的 Labels 映射。示例中的 trace 不属于 Database 的字段，因此它应该触发错误。

package main

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

type Config struct {
    Database Database           `json:"database"`
    Labels   map[string]any     `json:"labels"`
}

type Database struct {
    Host string `json:"host"`
    Port int    `json:"port"`
}

func decodeConfig(input []byte) (Config, error) {
    var cfg Config
    dec := json.NewDecoder(bytes.NewReader(input))
    dec.DisallowUnknownFields()
    if err := dec.Decode(&cfg); err != nil {
        return Config{}, err
    }
    return cfg, nil
}

func main() {
    cfg, err := decodeConfig([]byte(`{"database":{"host":"db.internal","port":5432,"trace":true},"labels":{"team":"api","trace":true}}`))
    fmt.Printf("cfg=%+v err=%v\n", cfg, err)
}

运行后会得到类似 json: unknown field "trace" 的错误。这里的 trace 出现在 database 对象里，解码器已经进入 Database 这个结构体目标，所以它不能被当作随手追加的键放过去。

嵌套 struct 会继续校验，但 map 不会变成白名单

标准库文档把适用范围写得很窄：当目标是结构体，并且对象键匹配不到非忽略的导出字段时，解码器返回错误。嵌套 Database 仍然是结构体，因此它共享这个规则；Labels 则是 map[string]any，它的职责就是承接动态键。

因此，下面这份输入中，labels.trace 并不会因为顶层启用了严格模式就报错；它落在 map 里，本来就是允许的动态键。若 trace 是不该出现的配置项，就不要把这一段定义成 map，或者在业务层对 map 的键再做一轮明确的白名单检查。

错误返回后不要继续使用半填充配置

Decode 失败时，目标值可能已经写入过部分字段。示例里的 decodeConfig 直接返回零值 Config{}，调用方只在 err == nil 时接收配置，这个边界比“记录日志后继续启动”可靠得多。

cfg, err := decodeConfig(body)
if err != nil {
    return fmt.Errorf("load service config: %w", err)
}
startServer(cfg)

如果接口允许向前兼容，可以把“固定字段”和“扩展字段”分开建模：固定部分使用 struct 严格解码，扩展部分显式使用 map，并在扩展键进入业务前检查允许集合。不要为了让旧客户端继续工作，把整份请求改成 map[string]any，这样会丢掉字段拼写错误的保护。

自定义 UnmarshalJSON 是另一道边界

类型实现 UnmarshalJSON 后，它接管了该类型的输入处理。外层解码器仍然能严格检查外层 struct 的字段，但自定义方法内部是否拒绝未知键，取决于自己的实现。常见做法是内部再次创建 json.Decoder 并调用 DisallowUnknownFields，或先解码到固定的辅助 struct。

排查时可以沿着这条顺序走：先看当前目标是不是 struct，再看字段是否有 json 标签，最后搜索目标类型是否实现了 UnmarshalJSON。这三步比单纯重复调用严格选项更快定位问题。

常见问题

DisallowUnknownFields 会检查 JSON 顶层所有层级吗？

它会在解码进入各个 struct 目标时检查对应对象键，但 map、interface 和自定义解码逻辑拥有自己的边界，不应理解成无条件的全量 schema 校验。

为什么 map[string]any 里的拼写错误没有报错？

因为 map 没有预先声明的字段集合，未知键对它来说就是普通键。需要白名单时，应换成 struct 或在业务层显式检查键名。

严格解码失败后能不能继续使用 cfg？

不建议。失败时可能已经写入部分字段，调用方应丢弃该值并返回错误，避免缺少关键配置却继续运行。

把判断收束成一条规则

遇到“为什么 DisallowUnknownFields 没拦住”时，先沿着目标类型追踪，而不是只看解码器创建的位置：固定字段用 struct，动态字段用 map 并配套白名单，自定义解码器内部重新承担严格校验。这样既能保留接口演进空间，也不会把拼写错误悄悄带进运行中的配置。