json解码重复键结果异常怎么办

如果同一个 JSON 对象里出现两次同名键，Go 的 encoding/json v1 通常不会把它当成语法错误。它会按照键出现的顺序处理：后面的值可能替换前面的值，也可能和前面的对象字段合并，所以“解码成功但结果不对”往往正是重复键造成的。

排查时先看三件事：原始 JSON 是否真的有重复键、目标是 map 还是 struct、重复键是否出现在嵌套对象里。若接口契约明确要求键唯一，最稳妥的做法是在业务解码前加一层重复键门禁。

先确认重复键确实是触发条件

先把收到的原始字节保存到安全的调试日志或脱敏样本中，再单独看对象键，而不是只打印最终的 Go 结构。下面的样例中，role 出现了两次，v1 会接受这份输入：

{
  "name": "Lin",
  "role": "reader",
  "role": "admin"
}

这类输入和缺少逗号、引号未闭合不是一回事。后者通常返回 *json.SyntaxError；重复键则可能没有错误，问题会延迟到权限、配置或字段判断阶段才暴露。也不要把 Decoder.DisallowUnknownFields 当成重复键检查，它只处理目标 struct 中不存在的字段。

按目标类型判断到底是谁覆盖了谁

同一份 JSON，解码目标不同，观察到的“异常”也不同。解到 map[string]any 时，同名键后出现的值会覆盖前一个值；解到 struct 的普通字段时，后面的标量通常也会成为最终值。

package main

import (
    "encoding/json"
    "fmt"
)

type Envelope struct {
    Role string `json:"role"`
}

func main() {
    data := []byte(`{"role":"reader","role":"admin"}`)

    var raw map[string]any
    if err := json.Unmarshal(data, &raw); err != nil {
        // 语法错误和类型错误要先返回，不能把结果当成可信输入。
        panic(err)
    }

    var env Envelope
    if err := json.Unmarshal(data, &env); err != nil {
        // 第二次解码只是为了对比不同目标类型的结果。
        panic(err)
    }

    // 两个目标都能得到 admin，但这不代表重复键是安全的。
    fmt.Println(raw["role"], env.Role)
}

嵌套对象要更谨慎。后一个对象可能只提供其中一个字段，解码到已经有值的 struct 字段时，其他字段仍可能保留；因此最终对象看起来像“两个版本拼在一起”。这就是文档所说的 replace 或 merge 取决于 Go 值类型。不要用“最后一个键覆盖全部对象”这个简单规则解释所有结果。

在解码前增加重复键门禁

如果重复键对业务没有明确意义，可以在调用 json.Unmarshal 前用 Decoder.Token 递归读取所有对象键。每进入一个对象就新建一个键集合；数组只负责继续递归，不共享外层对象的集合。

package main

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

var errDuplicateKey = errors.New("json object contains duplicate key")

// scanValue 消费一个完整 JSON 值，并递归检查每个对象的键。
func scanValue(dec *json.Decoder) error {
    token, err := dec.Token()
    if err != nil {
        return err
    }

    delim, ok := token.(json.Delim)
    if !ok {
        // 字符串、数字、布尔值和 null 没有子键，消费完成即可。
        return nil
    }

    switch delim {
    case '{':
        seen := make(map[string]struct{})
        for dec.More() {
            keyToken, err := dec.Token()
            if err != nil {
                return err
            }
            key := keyToken.(string)
            if _, exists := seen[key]; exists {
                // 发现重复键后立即拒绝，避免继续构造业务对象。
                return errDuplicateKey
            }
            seen[key] = struct{}{}
            if err := scanValue(dec); err != nil {
                return err
            }
        }
        _, err = dec.Token() // 消费对象结束符 }
        return err
    case '[':
        for dec.More() {
            if err := scanValue(dec); err != nil {
                return err
            }
        }
        _, err = dec.Token() // 消费数组结束符 ]
        return err
    default:
        return fmt.Errorf("unexpected delimiter %q", delim)
    }
}

func decodeUnique(data []byte, dst any) error {
    // 扫描器只读一遍输入；真正解码时重新创建 reader。
    dec := json.NewDecoder(bytes.NewReader(data))
    if err := scanValue(dec); err != nil {
        return err
    }
    return json.Unmarshal(data, dst)
}

生产代码还应把“重复键”与普通语法错误分开记录，并附上请求来源、接口版本和脱敏后的样本。这样下游看到的是明确的 4xx 输入错误，而不是一个已经被覆盖过的权限或配置对象。

把失败处理接入请求回路

可以按下面的顺序接入已有接口流水线：

1. 入口：保留原始字节的短期脱敏样本，先检查是否为空、是否超过大小上限。
2. 门禁：递归扫描对象键；发现重复键就返回可识别的客户端输入错误。
3. 解码：只有门禁通过后才调用 json.Unmarshal，再做业务字段校验。
4. 通知：把重复键计数按接口和调用方聚合，持续出现时回溯上游序列化逻辑。

如果项目已经采用 encoding/json/v2，官方文档说明它默认拒绝重复对象名称；但迁移时仍要确认工具链、构建标签和依赖使用的是哪一套 JSON 包。不要因为某个服务使用 v2，就假设所有仍调用 encoding/json v1 的边车、脚本或旧服务也会拒绝重复键。

常见问题

重复键会让 json.Unmarshal 返回错误吗？

对 v1 来说，默认不会仅因为重复键返回错误；语法错误、目标类型不匹配和数字溢出是另一类问题。需要唯一键语义时，应显式加扫描门禁或使用已经配置为拒绝重复名称的解码路径。

DisallowUnknownFields 能解决重复键吗？

不能。它只拒绝无法匹配到 struct 字段的未知键，不会把两个同名键变成错误。两者可以一起使用，但职责不同。

总结：先确认原始 JSON，再看目标类型的替换/合并语义，最后把重复键检查放到业务解码之前。只看最终 struct 很容易错过真正的输入问题。