Go encoding/json/v2 怎么用选项统一控制字段名匹配

把 Go 服务从 encoding/json 迁到 encoding/json/v2 时，字段名匹配往往是最先暴露的兼容差异之一。旧接口会宽松地接受大小写不同的成员名，而 v2 默认只接受与 Go 字段名或 json 标签完全一致的名称。需要统一兼容历史请求时，核心写法是在解码调用上增加 json.MatchCaseInsensitiveNames(true)；只有少数字段需要例外时，再用 case:ignore 或 case:strict 标签覆盖。

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

推荐先把“名称匹配策略”当作输入契约来决定：新接口保持 v2 的精确匹配；确实要接收历史客户端大小写变体时，才在该解码入口启用忽略大小写。不要为了一个字段名问题直接恢复整套 v1 默认选项。

先确认 v2 的默认行为

假设结构体字段声明为 UserID int `json:"userId"`。在 v2 默认设置下，JSON 成员 "userId" 可以命中；"USERID"、"UserId" 或 "user_id" 不会因为“看起来相似”就自动命中。这种精确匹配让接口契约更可预测，也减少同一份请求被多种拼写解释的空间。

“不命中”不一定等于报错。如果没有同时启用拒绝未知成员的策略，未匹配成员可能被忽略。因此迁移测试不能只看 err 是否为空，还要断言目标字段的最终值。

调用级选项：统一控制一次解码

MatchCaseInsensitiveNames 是调用选项，可以传给 json.Unmarshal。它只影响本次解码，适合在 API 边界、消息消费者或兼容层里明确选择策略，不会偷偷修改进程全局状态。

package main

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

type User struct {
    UserID int `json:"userId"`
}

func main() {
    data := []byte(`{"USERID": 42}`)

    var user User
    // 本次解码统一启用忽略大小写，历史键 USERID 可以命中 userId。
    err := json.Unmarshal(data, &user, json.MatchCaseInsensitiveNames(true))
    if err != nil {
        fmt.Printf("解码失败: %v\n", err)
        return
    }

    // 不只检查 err，还输出目标字段，确认名称确实完成了匹配。
    fmt.Printf("UserID=%d\n", user.UserID)
}

如果希望保持严格契约，不传这个选项即可；显式传 json.MatchCaseInsensitiveNames(false) 也能表达同样策略，尤其适合由公共选项集合组装调用参数的代码。将选项放在具体入口，比在业务结构体里到处复制兼容字段更容易审计。

字段级标签：给少数字段设置例外

调用级选项适合定义入口的统一策略，但真实系统常有例外：大部分新字段希望严格匹配，某个历史字段必须兼容；或者整个旧接口需要忽略大小写，但令牌字段不能接受变体。v2 的字段标签选项可以表达这两种情况。

package contract

type Payload struct {
    // LegacyID 即使调用保持默认严格模式，也允许忽略大小写匹配。
    LegacyID string `json:"legacyId,case:ignore"`

    // Token 即使调用启用了宽松模式，仍要求与标签 token 精确一致。
    Token string `json:"token,case:strict"`
}

case:ignore 和 case:strict 的字段级声明优先于调用级选项。这样，结构体本身就记录了稳定的字段契约：调用者可以设置默认策略，字段可以针对自身做更严格或更宽松的覆盖。

这里应克制使用 case:ignore。它适合已经存在多种大小写拼写、短期不能统一的外部协议字段，不适合给所有字段机械添加。越多字段进入宽松模式，越难发现客户端发错键名。

只容忍大小写时，单独约束分隔符

忽略大小写模式的“宽松”不只体现在字母大小写。名称比较通常还会忽略连字符和下划线，所以 user_id 也可能匹配 userId。这对兼容旧客户端很方便，但有些接口只想接受 USERID 这类大小写变体，不想把 snake_case 或 kebab-case 一并放进来。

这时可以组合 v1 兼容包提供的分隔符选项：

package decode

import (
    jsonv1 "encoding/json"
    jsonv2 "encoding/json/v2"
)

type Request struct {
    UserID int `json:"userId"`
}

func Decode(data []byte, dst *Request) error {
    // 忽略字母大小写，但不再忽略下划线和连字符差异。
    return jsonv2.Unmarshal(
        data,
        dst,
        jsonv2.MatchCaseInsensitiveNames(true),
        jsonv1.MatchCaseSensitiveDelimiter(true),
    )
}

这个组合下，USERID 可以按忽略大小写规则参与匹配，user_id 则不会因为下划线被忽略而自动命中。选择时要写清业务目标：兼容“大小写”，还是兼容“多种命名风格”。二者不是同一个策略。

精确匹配、歧义和重复成员

宽松匹配不是简单地把两边都转成小写。首先，精确匹配拥有优先级：如果输入名称与某个字段精确一致，即使还有别的字段在宽松规则下也可能匹配，精确字段仍应胜出。其次，如果不存在精确匹配，而多个字段都满足宽松规则，v2 会把它视为歧义，而不是随意选择一个字段。

重复成员也值得单独测试。例如同一对象同时出现 "userId" 和 "USERID"，启用忽略大小写后，它们可能被判断为指向同一名称空间。v2 对重复对象成员的处理更严格，不能假设“后一个覆盖前一个”永远成立。若请求来自不可信客户端，严格拒绝这类输入通常比默默覆盖更安全。

因此，打开宽松匹配前至少检查三件事：

• 同一结构体是否存在仅大小写、下划线或连字符不同的标签；
• 客户端是否可能同时发送两种拼写，造成重复名称；
• 接口是否把“未知字段被忽略”误当成“字段成功兼容”。

不要为一个选项直接恢复整套 v1 行为

DefaultOptionsV1() 可以帮助完整模拟旧接口的多项语义，其中也包含名称匹配相关设置。但它并不是“只兼容字段名”的快捷方式，还会同时影响其他 JSON 行为。若问题边界只是历史客户端的大小写拼写，应只开启 MatchCaseInsensitiveNames(true)，必要时再组合分隔符选项。

用表驱动测试冻结输入契约

字段名兼容最怕“代码能运行，但策略与预期不同”。表驱动测试应覆盖精确名称、大小写变体、下划线变体、重复成员和字段级覆盖，而不是只放一个成功样例。

package contract_test

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

type Input struct {
    UserID int `json:"userId"`
}

func TestNameMatching(t *testing.T) {
    tests := []struct {
        name string
        body string
        want int
    }{
        {name: "精确名称", body: `{"userId":1}`, want: 1},
        {name: "大小写变体", body: `{"USERID":2}`, want: 2},
        {name: "下划线变体", body: `{"user_id":3}`, want: 3},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            var got Input
            // 此测试刻意启用宽松名称匹配，以冻结兼容入口的行为。
            err := json.Unmarshal(
                []byte(tt.body),
                &got,
                json.MatchCaseInsensitiveNames(true),
            )
            if err != nil {
                t.Fatalf("解码失败: %v", err)
            }
            if got.UserID != tt.want {
                t.Fatalf("UserID=%d, want %d", got.UserID, tt.want)
            }
        })
    }
}

生产测试还应增加两个负例：同时提交 userId 与 USERID，确认重复成员按预期失败；构造两个宽松规则下可能冲突的字段，确认歧义不会被悄悄解析。若组合了分隔符选项，则把 user_id 的预期改为“不命中”，并断言字段保持零值或由未知字段策略返回错误。

落地清单

• 先列出该入口真实接收过的 JSON 键名，而不是凭感觉打开兼容模式；
• 新接口优先使用 v2 默认精确匹配，旧接口在调用点显式开启兼容；
• 只有个别历史字段时使用 case:ignore，敏感字段使用 case:strict；
• 明确下划线和连字符是否属于兼容范围，必要时约束分隔符；
• 检查结构体标签在宽松规则下是否产生歧义；
• 测试重复名称、未知字段和目标字段最终值，不只断言错误为空；
• 不要仅为名称匹配启用 DefaultOptionsV1()，避免无意恢复其他旧语义。

结论

encoding/json/v2 的字段名策略可以分成三层：默认精确匹配提供稳定基线，MatchCaseInsensitiveNames(true) 为一次解码统一放宽大小写，case:ignore 与 case:strict 为具体字段设置例外。若还要控制下划线和连字符，再组合分隔符选项。真正可靠的迁移不是“能解码就算完成”，而是把精确命中、宽松命中、歧义和重复成员都写进测试，让输入契约长期可见。