Go json.Decoder 如何只拒绝嵌套对象中的未知字段

Go 的 encoding/json 默认会忽略 JSON 中没有对应 Go 字段的键。给最外层 json.Decoder 调用 DisallowUnknownFields，虽然能抓住拼写错误，却也会让上游新增一个顶层字段就直接失败。需要“只拒绝嵌套对象中的未知字段”时，做法是把严格策略放进目标嵌套类型自己的 UnmarshalJSON：外层保持普通解码，指定对象内部再创建一个开启严格模式的 Decoder。

如果只想让嵌套结构体拒绝未知字段，外层字段保留宽松解析的行为，可以给对应嵌套类型单独实现 json.Unmarshaler 接口，在自定义解析逻辑内部新建带 DisallowUnknownFields() 的临时 Decoder 处理该段嵌套 JSON 数据，外层就维持默认的宽松解析逻辑即可。

为什么全局开启严格模式不适合兼容接口

假设请求外层是 Envelope，其中的 Profile 是需要严格校验的用户资料。调用 Decoder.DisallowUnknownFields 后，Envelope 和 Profile 的未知键都会被拒绝；而不调用它时，两层都会按默认规则忽略未知键。标准库没有提供“只对某个 JSON 路径开启”的开关，所以需要把严格范围缩小到 Profile。

package main

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

type Envelope struct {
    Profile Profile `json:"profile"`
}

type Profile struct {
    DisplayName string `json:"display_name"`
}

func main() {
    input := `{"trace_id":"new-field","profile":{"display_name":"Lin","nicknmae":"typo"}}`
    var req Envelope
    dec := json.NewDecoder(strings.NewReader(input))
    // 外层不打开严格模式，兼容未来新增的 trace_id 等字段。
    if err := dec.Decode(&req); err != nil {
        fmt.Println(err)
    }
}

上面的代码在默认规则下不会因为 trace_id 或 nicknmae 报错。注意这里故意把 nickname 写成了 nicknmae，它正是严格校验希望尽早发现的请求错误。

在嵌套类型内部开启 DisallowUnknownFields

让 Profile 自己决定解码策略即可。UnmarshalJSON 中声明一个新的类型 plainProfile，它拥有相同字段但没有 Profile 的方法集，再把数据解码到这个别名值里。否则直接解码到 Profile 会再次调用 UnmarshalJSON，形成递归。

package main

import (
    "bytes"
    "encoding/json"
)

type Envelope struct {
    Profile Profile `json:"profile"`
}

type Profile struct {
    DisplayName string `json:"display_name"`
    Age         int    `json:"age"`
}

func (p *Profile) UnmarshalJSON(data []byte) error {
    // 别名类型保留字段和 json 标签，但不会再次进入本方法。
    type plainProfile Profile

    strict := json.NewDecoder(bytes.NewReader(data))
    // 严格策略只属于 Profile，不会影响 Envelope 的其他字段。
    strict.DisallowUnknownFields()

    var value plainProfile
    if err := strict.Decode(&value); err != nil {
        // 错误会保留 json: unknown field "..." 这类定位信息。
        return err
    }
    *p = Profile(value)
    return nil
}

外层仍然这样解码：

var req Envelope
dec := json.NewDecoder(strings.NewReader(`{"trace_id":"v2","profile":{"display_name":"Lin","nicknmae":"typo"}}`))
// 不在这里调用 DisallowUnknownFields，保持外层字段向前兼容。
if err := dec.Decode(&req); err != nil {
    fmt.Println(err) // json: unknown field "nicknmae"
}

解码器进入 Profile 字段时会调用它的 UnmarshalJSON，因此 nicknmae 被拒绝；trace_id 在 Envelope 中没有对应字段，却仍按默认规则被忽略。Profile 内部继续嵌套普通 struct 时，严格 Decoder 会沿着这次结构解码继续检查。

数组、map 和 RawMessage 的校验边界

这套方式按目标字段的实际类型生效。数组中的元素如果是 []Profile，每个对象都会进入 Profile.UnmarshalJSON；如果是 []map[string]any，map 本身没有“未声明字段”，因此不存在未知字段错误。json.RawMessage 也只是暂存原始 JSON，只有后续把它交给严格 Decoder 时，校验才会发生。

还要留意自定义解码方法的覆盖范围：只要某处目标类型是 Profile，这套严格规则就会被复用。如果同一结构在配置读取时允许扩展、在 HTTP 请求时不允许扩展，建议拆成两个用途明确的类型或包装类型，不要在方法里根据调用方猜测策略。

上线前检查这几个细节

第一，字段必须使用正确的导出名和 json 标签；被标记为 json:"-" 的字段本来就不会参与匹配。第二，未知字段错误通常先报告遇到的一个键，如果接口需要一次返回全部错误，应在解码后增加专门的字段白名单校验。第三，DisallowUnknownFields 解决的是字段边界，不会自动检查必填、取值范围或业务状态，这些仍应交给请求校验层。

常见问题

能不能只对 profile.address 再严格一层？

可以，让 Address 也实现自己的 UnmarshalJSON，或在 Profile 内部把它交给独立严格 Decoder。关键是每个严格边界都要有明确的目标类型。

为什么不用 json.Unmarshal 直接完成？

json.Unmarshal 没有开启 DisallowUnknownFields 的参数。需要严格策略时，应创建 json.Decoder 并调用该方法。

以后想让整个请求都严格怎么办？

可以在最外层 Decoder 上调用 DisallowUnknownFields，但这会改变兼容策略。建议把它作为明确的接口版本或灰度配置，而不是悄悄替换现有行为。