Go encoding/json/v2 RejectUnknownMembers 怎样拒绝多余字段

Go encoding/json/v2 解码结构体时，输入 JSON 多出字段并不会默认报错；未知成员默认会被忽略。如果接口契约要求“多一个字段也要暴露”，就在解码调用中加入 json.RejectUnknownMembers(true)。它只影响反序列化，不会改变 JSON 的编码结果。

官方文档：https://pkg.go.dev/encoding/json/v2

最小改法是给 json.Unmarshal 传入 json.RejectUnknownMembers(true)；发生错误后，再从 json.SemanticError 中取出 ErrUnknownName 和 JSONPointer，就能定位多余字段。

先确认默认行为：未知成员为什么没有报错

结构体解码只关心能映射到目标字段的成员。下面的输入包含 name 和 debug，但目标结构体只声明了 Name。不传额外选项时，debug 会被忽略，解码仍可能成功。

package main

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

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

func main() {
    input := []byte(`{"name":"demo","debug":true}`)
    var req Request

    // 默认策略允许未知成员，适合需要向后兼容的输入。
    err := json.Unmarshal(input, &req)
    fmt.Printf("name=%q err=%v\n", req.Name, err)
}

这里的关键不是 Go 结构体有没有字段，而是调用方是否选择了严格的未知成员策略。不要把“解码成功”理解成“输入字段全部被接收”。

用 RejectUnknownMembers 开启严格解码

把选项作为 json.Unmarshal 的第三个参数传入即可。未知成员属于反序列化阶段的问题，所以该选项对 Marshal 没有作用，也不能替代业务层的字段值校验。

package main

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

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

func main() {
    input := []byte(`{"name":"demo","debug":true}`)
    var req Request

    // 严格策略把未知 JSON 成员转换成解码错误。
    err := json.Unmarshal(input, &req, json.RejectUnknownMembers(true))
    fmt.Printf("name=%q err=%v\n", req.Name, err)
}

实务上可以把这个选项放在边界层：外部请求、配置文件和消息反序列化使用严格策略；内部为了兼容旧数据而保留的宽松读取，则单独声明原因，避免默认行为悄悄扩散。

提取未知字段位置

只打印 err.Error() 能看到人类可读的信息，但不利于日志分类。encoding/json/v2 提供了结构化错误信息：用 errors.AsType 取得 *json.SemanticError，确认其 Err 是 json.ErrUnknownName，再从 JSONPointer 读取路径。

package main

import (
    "errors"
    "fmt"
    "encoding/json/v2"
)

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

func main() {
    input := []byte(`{"name":"demo","debug":true}`)
    var req Request

    // 先启用严格策略，再把未知字段转换成可分类的错误。
    err := json.Unmarshal(input, &req, json.RejectUnknownMembers(true))
    if err == nil {
        return
    }

    // 只对未知成员错误提取路径，其他语义错误交给上层处理。
    if sem, ok := errors.AsType[*json.SemanticError](err); ok && sem.Err == json.ErrUnknownName {
        fmt.Printf("unknown=%q path=%s\n", sem.JSONPointer.LastToken(), sem.JSONPointer)
    }
}

嵌套对象出现问题时，JSONPointer 保留完整位置，LastToken() 只取最后一段字段名。这样日志可以同时保存“完整路径”和“字段标签”，既适合定位，也适合统计。

三个容易混淆的边界

如果某个对象本来就允许扩展成员，不要为了“统一严格”把它误设为拒绝模式；可以把可扩展部分设计成明确的 map 或单独的扩展字段。严格策略的价值在于让契约边界显式，而不是让所有输入都变得脆弱。

相关问题

RejectUnknownMembers 会影响 Marshal 吗？

不会。官方文档将它定义为只影响 unmarshaling 的选项，编码时不会因为结构体中不存在某个输入字段而改变输出。

为什么要取 SemanticError 而不是只比较错误字符串？

结构化错误能区分未知成员和其他语义错误，并保留 JSON Pointer 路径；字符串适合展示，不适合作为长期稳定的程序判断条件。

未知字段拒绝等于业务参数校验吗？

不等于。它只回答“字段名是否属于目标结构体”，长度、范围、权限和字段之间的组合关系仍需业务代码处理。