Go JSON 字段大小写不一致为什么仍然被填充

这是 encoding/json v1 的既定行为：把 JSON 对象解码到结构体时，Go 会先找与结构体字段名或 json 标签完全相同的键；如果没有精确匹配，还会接受大小写不敏感的匹配。所以 JSON 中的 USERNAME、username 或 UserName，在没有冲突的情况下，都可能填入同一个字段。

大小写不一致仍能填充，不是标签失效，而是 v1 为兼容历史数据提供了大小写不敏感的结构体字段匹配。若接口必须严格区分键名，需要在解码前做精确键名检查，或评估使用 v2 的匹配语义。

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

下面只讨论 JSON 对象到 Go 结构体的字段匹配，不把它延伸成 JSON 语法校验、业务字段校验或所有版本的默认行为。

为什么 json:"userName" 还能接收 USERNAME

看一个最小场景：结构体标签写的是 userName，输入却使用了全大写键。v1 的 Unmarshal 会把标签作为匹配名，先尝试精确比较；精确键不存在时，再进行大小写不敏感比较，因此 USERNAME 仍可落到 UserName 字段。

package main

import (
    "encoding/json"
    "fmt"
)

type Profile struct {
    // 标签定义首选的 JSON 键名，但 v1 仍接受大小写不敏感的匹配。
    UserName string `json:"userName"`
}

func main() {
    payload := []byte(`{"USERNAME":"alice"}`)
    var p Profile
    if err := json.Unmarshal(payload, &p); err != nil {
        // 真实服务中应把解码错误交给请求层处理，不要静默吞掉。
        panic(err)
    }
    // v1 的兼容匹配会让这里得到 alice。
    fmt.Println(p.UserName)
}

文档中的关键点是“优先精确匹配，但也接受大小写不敏感匹配”。因此标签并不是正则表达式，也不是强制拒绝其他大小写写法的约束。标签的作用是指定常规编码名和首选匹配名，而不是自动开启严格模式。

这种兼容只发生在结构体匹配上

不要把“字段大小写不敏感”理解成 JSON 本身会被统一改成小写。解码目标不同，结果也不同：

另外，未知字段默认会被忽略，但这和大小写兼容是两件事：一个键只要能匹配到结构体字段，就不再属于“未知字段”。

接口必须严格区分大小写时怎么做

如果外部协议明确规定只接受 userName，可以先把对象解码到 map[string]json.RawMessage，逐个检查键是否在允许集合中，再把原始 JSON 解码到结构体。这样严格检查和业务字段解码各自负责一件事。

package main

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

type Profile struct {
    UserName string `json:"userName"`
}

func decodeExact(data []byte, dst *Profile) error {
    var fields map[string]json.RawMessage
    if err := json.Unmarshal(data, &fields); err != nil {
        // 先保证输入是 JSON 对象，语法错误直接返回。
        return err
    }
    allowed := map[string]struct{}{"userName": {}}
    for key := range fields {
        if _, ok := allowed[key]; !ok {
            // 精确比较不会把 USERNAME 当成 userName。
            return fmt.Errorf("unexpected JSON field %q", key)
        }
    }
    // 键名检查通过后再使用结构体解码，保留正常的类型错误处理。
    dec := json.NewDecoder(bytes.NewReader(data))
    dec.DisallowUnknownFields()
    return dec.Decode(dst)
}

这里的 DisallowUnknownFields 只是第二道结构体字段保护，不能替代前面的大小写精确检查。因为对 v1 来说，USERNAME 已经能够匹配到 userName，单独开启它并不会把这个键判为未知。

什么时候继续兼容，什么时候改成严格

内部服务接收历史客户端数据时，继续使用 v1 的兼容行为通常更稳，但应在接口文档中写清允许的键名，并在业务层记录不规范输入。对签名、配置、跨团队协议或需要拒绝拼写变体的入口，建议采用上面的原始键预检，避免同一字段存在多个外观。

当前官方文档还区分了 encoding/json v1 与 encoding/json/v2：v1 默认接受大小写不敏感匹配，而 v2 默认使用精确、大小写敏感的匹配。迁移到 v2 还会带来其他语义差异，因此不能只因为这一条规则就直接替换包；应先对现有输入和测试样例做兼容性评估。

常见问题

给字段加了 json 标签，为什么还不能拒绝错误大小写？ 标签指定的是匹配名和编码名，encoding/json v1 仍保留大小写不敏感的回退匹配。

DisallowUnknownFields 能解决这个问题吗？ 不能单独解决。它拒绝的是完全匹配不到结构体字段的键，已被 v1 兼容匹配识别的错误大小写不会被它当成未知字段。

map 能不能用来观察客户端原始键名？ 可以。先解码到 map[string]json.RawMessage 能保留键名，再按接口白名单做大小写敏感检查。