json字段大小写匹配不符合预期怎么办

Go 的 encoding/json 将 JSON 对象解码到结构体时，允许字段名忽略大小写匹配；同一个输入键对应多个候选字段时优先精确匹配。给字段写 JSON tag，并不会自动变成大小写严格检查。如果接口必须只接受约定拼写，应在进入业务结构体之前，按精确键名集合检查输入，再处理对应值。

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

建立输入对照基线

考虑一个昵称更新接口，约定输入键为 display_name。结构体导出字段 DisplayName 配置名为 display_name 的 JSON tag 后，下面三组单键输入都可能匹配该字段：

{"display_name":"青禾"}

第一组使用约定的键名；另外两组分别将它换成 DISPLAY_NAME 和 Display_Name，保持值不变。这组对照只改变大小写，适合先区分“tag 没写对”和“默认匹配比较宽松”。大小写折叠不会自动去掉下划线，所以 displayName 与 display_name 不是仅有大小写差异。

我会先把是否允许这些变体写成协议要求：内部兼容输入可以选择接受，严格外部接口则可以拒绝。这个选择是工程判断，不应从“解码成功”反推“输入已经符合协议”。本文用预期输入结果讨论正确性，没有虚构压测数据或亲历事故。

解释 tag 与未知字段检查

JSON tag 确定字段使用的 JSON 名称；导出的 Go 字段才是常规结构体解码目标。DisallowUnknownFields 则让 Decoder 对无法匹配的对象键返回错误，它使用的仍然是解码器匹配规则，因此不是大小写敏感开关。用它配合 tag 后，大小写变体依然可能被识别为已知字段。

还要区分两个容易混淆的规则：精确匹配优先描述的是一个输入键选择哪个结构体字段；它不意味着先遇到精确拼写后，后面的其他大小写形式都将被忽略。输入成员按遇到的顺序处理；对于简单字符串字段，后续映射到同一字段的值可能覆盖前面的值。

增加精确键名门控

下面给出一个限定很清楚的实现：只接受顶层对象，唯一允许字段是 display_name，要求它恰好出现一次且值为字符串。它逐个读取键，在字符串层面精确比较，因此不会因为普通结构体匹配规则而接纳 DISPLAY_NAME。重复键、null 和尾随第二个 JSON 值也会拒绝。

package request

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

// Profile 是业务对象；键名规则由入口解析函数显式负责。
type Profile struct {
    DisplayName string
}

func ParseProfile(data []byte) (Profile, error) {
    var result Profile
    dec := json.NewDecoder(bytes.NewReader(data))
    token, err := dec.Token()
    if err != nil {
        return result, err
    }
    if token != json.Delim('{') {
        return result, errors.New("必须提供 JSON 对象")
    }

    seen := false
    for dec.More() {
        token, err = dec.Token()
        if err != nil {
            return Profile{}, err
        }
        key, ok := token.(string)
        if !ok || key != "display_name" {
            return Profile{}, fmt.Errorf("不允许的字段名: %v", token)
        }
        if seen {
            return Profile{}, errors.New("display_name 不得重复")
        }
        seen = true

        // 使用指针接收以区分 JSON null 与有效空字符串。
        var name *string
        if err := dec.Decode(&name); err != nil {
            return Profile{}, err
        }
        if name == nil {
            return Profile{}, errors.New("display_name 不能为 null")
        }
        result.DisplayName = *name
    }

    // 确认顶层对象完整结束，并且后面没有第二个 JSON 值。
    end, err := dec.Token()
    if err != nil {
        return Profile{}, err
    }
    if end != json.Delim('}') {
        return Profile{}, errors.New("JSON 对象未结束")
    }
    var extra json.RawMessage
    if err := dec.Decode(&extra); !errors.Is(err, io.EOF) {
        if err != nil {
            return Profile{}, err
        }
        return Profile{}, errors.New("只允许一个 JSON 对象")
    }
    if !seen {
        return Profile{}, errors.New("缺少 display_name")
    }
    return result, nil
}

这个函数放进项目的 request 包即可由调用方调用。输入数据需要先经过项目自己的大小限制；示例接收的是已在内存中的字节切片，没有替调用方限制 HTTP 请求体。函数返回错误时返回空业务对象，调用方不应继续使用中间已解析出的字段。

这里比较的是 JSON 解码后的键字符串。使用 Unicode 转义写出的等价键，也可能解码为 display_name 并被接受。若协议要求连原始转义写法都固定，那属于原始字节格式约束，需要另行定义，不能把精确键字符串比较说成逐字节相同。

比较预期结果与性能测试方法

表中是按接口契约给出的预期结果，不是本机测试报告。测试时应让每一行成为独立用例，再加入数字、数组、损坏 JSON、尾随对象和有效空字符串等输入。空字符串在本文方案中允许；是否必须非空，还应由业务规则决定。

性能方面，Token 调用、键判断与错误信息都有开销，不能把“限制更严格”写成“解码更快”。如果它处于高吞吐入口，应使用同一 Go 工具链、同一数据规模和相同有效输入比例，比较 ns/op、B/op 与 allocs/op。错误路径和正常路径分别测量，避免把提前拒绝的短路径与完整解码混在一起得出结论。这里没有执行压测，所以不提供提升百分比。

列出嵌套和重复键限制

先解码成 map[string]json.RawMessage 再检查键集合，能够方便地做大小写精确比较，但同名重复键的信息已经丢失，不能再可靠计数。本文选择逐键读取，是为了同时保留重复检测能力。

这个例子只支持一个顶层字符串字段。真实协议出现嵌套对象时，每个层级都要定义自己的允许键、必填项和重复规则；不能只检查最外层就宣称整个文档严格。也不要先把全部键强制转小写来“修复”输入，那会合并原本不同的键并掩盖客户端错误。

json.Valid 能检查键大小写吗？

不能。它检查 JSON 语法有效性，不负责业务字段拼写、必填项或重复规则。

应该删除 tag 吗？

删除 tag 会改变字段名称映射，不能解决需要严格协议的问题。应先明确对外名称，再选择入口检查方式。

这套方案能直接替换所有 JSON 接口吗？

不能。它刻意针对单字段对象。采用前要评估现有客户端是否使用别名或大小写变体，并给出明确迁移安排。

规则参考：https://pkg.go.dev/encoding/json#Unmarshal；实现说明：https://go.dev/src/encoding/json/decode.go。本文针对 encoding/json 的传统兼容语义，其他 JSON 包或 API 的默认行为应另查相应文档。