Go encoding/json/v2 怎么按字段选项控制严格解码

如果一个 Go 接口把外部 JSON 直接解码进业务结构体，真正需要先决定的不是“能不能解析”，而是“哪些输入应该被接受”。encoding/json/v2 把这件事拆成了可组合的 Options 和字段级 json 标签：调用方可以统一拒绝未知成员，结构体作者也可以只对少数兼容字段放宽大小写规则。

官方地址：https://pkg.go.dev/encoding/json/v2

最实用的落地方式是：对写入数据库、签名校验或配置加载的输入默认使用严格策略；对需要兼容旧客户端的字段，用 case:ignore 做局部例外；遇到失败时读取 SemanticError 的 JSON Pointer，而不是只打印一行模糊的错误文本。下面的代码使用 Go 1.27 的正式 API，示例输出是解释性结果。

先分清 v2 默认行为与严格选项

Go 1.27 提供了 encoding/json/v2 和底层的 encoding/json/jsontext。本文只讨论前者的语义解码。v2 默认拒绝非法 UTF-8 和 JSON 对象中的重复名称；但未知成员默认仍会被忽略。也就是说，“严格”不是一个单独的开关，而是多项输入契约共同决定的结果。

因此，接口层通常先使用 RejectUnknownMembers 解决字段契约问题，再根据已知的历史客户端决定是否放宽某个字段。不要把“全局忽略未知字段”和“全局大小写不敏感”当成默认模板，否则新增拼写错误可能会静默进入系统。

用 RejectUnknownMembers 拒绝接口外字段

调用级选项适合放在边界函数中。下面的 decodeRequest 把未知成员视为契约错误：客户端多传了字段、字段拼写错了，或者服务端结构体还没有升级时，都会在解码阶段失败。

package main

import (
    "fmt"

    json "encoding/json/v2"
)

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

func decodeRequest(data []byte) (CreateUser, error) {
    var req CreateUser

    // 边界输入使用严格未知字段策略，避免拼写错误被静默忽略。
    err := json.Unmarshal(data, &req, json.RejectUnknownMembers(true))
    if err != nil {
        return CreateUser{}, fmt.Errorf("decode create user: %w", err)
    }
    return req, nil
}

例如输入中出现 emali 而不是 email 时，严格模式会返回错误。这里的重点不是让调用方拥有更多字段，而是让接口在字段契约发生偏差时尽早失败。对公共 API 可以把错误转换成稳定的 4xx 响应；对内部配置则可以直接阻止启动。

如果旧客户端确实会发送暂时无害的扩展字段，可以先在适配层使用默认策略，或者把扩展字段显式建模为 map[string]jsontext.Value。不要为了兼容而在所有入口关闭未知字段检查，因为不同入口的兼容期限可能并不相同。

用字段级 case 标签保留局部兼容

调用级 MatchCaseInsensitiveNames(true) 会影响整个结构体。更稳妥的做法是把兼容范围缩小到确实存在历史数据的字段：使用 case:ignore 接受大小写、短横线和下划线的差异，使用 case:strict 强调某个字段必须精确匹配。

type ImportOptions struct {
    // 历史配置中可能出现 Display_Name、display-name 等写法。
    DisplayName string `json:"displayName,case:ignore"`

    // 新增安全字段只接受精确名称，防止相近拼写被误认为同一字段。
    AccessToken string `json:"accessToken,case:strict"`
}

func decodeConfig(data []byte) (ImportOptions, error) {
    var cfg ImportOptions

    // 未知成员仍然拒绝；字段标签只调整已声明字段的匹配规则。
    err := json.Unmarshal(data, &cfg, json.RejectUnknownMembers(true))
    return cfg, err
}

字段级规则优先于调用级的同类选项。这样可以同时满足两类要求：接口整体拒绝未知字段，而一个经过评估的旧字段仍能接受历史大小写写法。需要注意，字段标签的兼容不是“自动清洗所有输入”，它只影响名称匹配，不会把类型错误变成合法值。

如果一个字段未来也要收紧，建议先记录实际输入来源，再移除 case:ignore，并在迁移窗口中对旧客户端给出明确提示。把兼容标签长期留在核心安全字段上，往往比一次迁移更难维护。

组合选项时怎样避免把作用域弄混

Options 可以传入多个值，后面的选项会覆盖前面的同类设置。建议把通用边界策略集中在一个函数里，再把少数场景的例外作为参数传入；不要在多个业务函数里散落一组看起来相同、实际已不一致的选项。

func strictOptions(allowLegacyCase bool) json.Options {
    // 先拒绝未知成员；兼容大小写只作为显式的边界选择。
    opts := json.RejectUnknownMembers(true)
    if allowLegacyCase {
        opts = json.JoinOptions(
            opts,
            json.MatchCaseInsensitiveNames(true),
        )
    }
    return opts
}

func decodeWithPolicy(data []byte, allowLegacyCase bool) (ImportOptions, error) {
    var cfg ImportOptions

    // 业务调用点只传入策略，避免重复拼接 Options。
    err := json.Unmarshal(data, &cfg, strictOptions(allowLegacyCase))
    return cfg, err
}

如果结构体已经使用了 case:strict 或 case:ignore，字段级标签会覆盖调用级的大小写匹配设置。调用级选项因此更适合表达“这一类入口的默认政策”，字段级标签则适合表达“这个字段的历史事实”。

从 SemanticError 读取具体错误位置

只记录 err.Error() 往往不够。v2 的语义错误可以通过 errors.AsType 提取 *json.SemanticError，其中的 JSON Pointer 能指出错误所在的对象路径；当未知成员被拒绝时，底层错误可以与 json.ErrUnknownName 对比。

import (
    "errors"
    "fmt"

    json "encoding/json/v2"
)

func explainDecodeError(err error) string {
    // 先取结构化错误，便于把稳定字段返回给日志或接口层。
    sem, ok := errors.AsType[*json.SemanticError](err)
    if !ok {
        return fmt.Sprintf("非语义错误：%v", err)
    }

    if errors.Is(sem.Err, json.ErrUnknownName) {
        // LastToken 是未知成员名，JSONPointer 是它在输入中的路径。
        return fmt.Sprintf("未知字段 %q，路径 %s", sem.JSONPointer.LastToken(), sem.JSONPointer)
    }
    return fmt.Sprintf("JSON 路径 %s：%v", sem.JSONPointer, sem.Err)
}

错误展示时可以把字段路径返回给开发者，但不建议把完整的原始 JSON 一起写入普通业务日志，尤其是输入可能包含令牌、身份证明或个人资料时。错误定位和原文脱敏应当是两件事：前者帮助排错，后者保护数据。

按输入来源选择严格模式与兼容模式

可以把解码入口分成三层：外部请求层、内部配置层和历史数据迁移层。外部请求层优先拒绝未知成员；内部配置层通常也应该严格，以便配置错误在启动时暴露；历史数据迁移层可以临时使用兼容选项，但要把兼容期限、样本和退出条件写进迁移记录。

• 公共接口：使用 RejectUnknownMembers(true)，错误通过结构化字段返回，不回显完整原文。
• 严格配置：默认大小写匹配，关键字段显式使用 case:strict，启动失败要给出 JSON Pointer。
• 旧数据导入：只在明确的适配层放宽规则，导入完成后再用严格模式重读或执行迁移检查。
• 不可信文本：不要因为兼容需求就同时打开非法 UTF-8 和重复键选项；这些行为会改变输入的解释方式。

未知字段默认会被拒绝吗？

不会。v2 默认忽略未知成员，需要显式传入 json.RejectUnknownMembers(true)。如果业务契约要求字段不能多也不能少，还要另外检查必填字段的零值或使用独立的业务校验。

调用级大小写不敏感和字段级标签怎么选？

如果整个输入来自同一种历史命名规则，可以考虑调用级选项；只对少数字段存在兼容事实时，优先字段级标签。字段级标签能缩小影响范围，也更方便未来逐个收紧。

开启严格未知字段后，能否保留扩展字段？

可以把扩展字段显式设计成结构体成员或独立的扩展对象，再对扩展对象采用自己的解码策略。不要依赖“先忽略未知字段、以后再想起来处理”的隐式扩展机制。

v1 的 encoding/json 还能继续用吗？

可以。Go 1.27 仍然支持原有 encoding/json，并且它的实现已由 v2 支撑；是否迁移到 encoding/json/v2 应由输入兼容性、错误处理和测试覆盖共同决定，不需要一次性切换全部调用点。

小结：严格解码的关键不是把所有选项都打开，而是先确定输入契约，再按作用域配置。用 RejectUnknownMembers 收紧调用边界，用 case:ignore 为历史字段保留局部兼容，用 case:strict 保护关键名称，再通过 SemanticError 提供可定位、可脱敏的错误信息，就能让 encoding/json/v2 的新能力落到真实接口上。