json/v2 遇到重复对象成员为什么会报错

encoding/json/v2 遇到重复对象成员时报错，是因为它默认把同名成员视为语义不明确的 JSON 输入。例如 {"user":"alice","user":"bob"} 同时给出了两个 user 值，不同实现可能选择覆盖、合并或保留其中一个。v2 选择先拒绝，避免鉴权服务和业务服务对同一请求得出不同结论。

重复成员为什么不该静默覆盖

JSON 规范没有为对象中的重复名规定唯一的处理结果。一个服务可能使用后出现的值，另一个服务可能合并数组或保留先出现的值。若前者负责鉴权、后者负责执行，就可能出现“校验的是一个用户，执行的是另一个用户”的解析差异。

因此 v2 的默认行为不是偶然的严格检查，而是把不确定性留在输入边界。错误发生在 JSON token 层，通常应先检查原始请求或消息，而不是立即修改 Go 结构体标签。

v1 与 v2 的默认语义不同

这个差异也解释了迁移时的现象：旧代码能处理的第三方 JSON，切换到 v2 后可能在第一次出现重复名的位置失败。失败本身是有效信号，说明输入需要被修复、规范化，或者被明确标记为兼容数据。

用最小调用看清默认拒绝和兼容放宽

下面的示例只展示输入边界，不代表真实业务请求。默认调用保持严格模式；第二次调用才显式允许重复名。代码中的选项会同时影响编码和解码，不能把它当成“只忽略某一次报错”的日志开关。

package main

import (
    "fmt"

    "encoding/json/jsontext"
    "encoding/json/v2"
)

type Envelope struct {
    User string `json:"user"`
}

func main() {
    // 这个输入含有两个同名成员，默认 v2 会拒绝它。
    raw := []byte(`{"user":"alice","user":"bob"}`)
    var strict Envelope
    if err := json.Unmarshal(raw, &strict); err != nil {
        fmt.Println("strict:", err)
    }

    // 只有兼容旧数据时才显式放宽；结果取决于处理顺序，必须记录原因。
    var legacy Envelope
    if err := json.Unmarshal(raw, &legacy, jsontext.AllowDuplicateNames(true)); err != nil {
        fmt.Println("compat:", err)
        return
    }
    fmt.Println("compat user:", legacy.User)
}

兼容模式下不能把最终字段值当成跨实现都稳定的协议事实。若消息来自自己维护的生成器，最好的修复仍是让生成器只输出一次成员名；如果来自外部系统，则应在适配层记录来源、保留原始错误上下文，并把放宽范围限制在这一条输入链路。

别把重复名和大小写、嵌入字段冲突混为一谈

"user" 与 "User" 是否算作同一成员，还会受到结构体字段匹配选项影响。v2 默认使用更严格的大小写匹配；如果主动开启大小写不敏感匹配，两个不同拼写可能同时命中同一个 Go 字段，从而触发重复名判断。此时问题仍然来自 JSON 名称解析规则，但原因不再是字面上完全相同的两个键。

type Request struct {
    User string `json:"user"`
}

// 只有确实要兼容大小写不统一的上游时才打开该选项。
var req Request
err := json.Unmarshal(data, &req, json.MatchCaseInsensitiveNames(true))

还要检查嵌入字段和 fallback map：多个字段经过标签或嵌入提升后可能得到同一个 JSON 名称。这类冲突发生在 Go 类型的表示层；可以通过明确标签、取消嵌入或拆分 DTO 解决，不应一律使用 AllowDuplicateNames 掩盖模型歧义。

修复顺序：先改上游，再做局部兼容

可以按下面的顺序处理：

1. 在消息入口记录原始 JSON 的字段位置和来源，确认确实存在重复名。
2. 若生成器归自己维护，修复序列化逻辑或模板，确保一个对象只产生一个成员名。
3. 若上游暂时无法修改，把 AllowDuplicateNames(true) 放在专门的适配函数中，不要扩散到整个服务。
4. 为适配层增加重复名、大小写变体和嵌入字段的回归样例，并在日志中注明兼容策略。

当重复字段承载权限、金额、状态或路由信息时，不建议为了恢复旧接口而全局放宽。可以先把输入转换成内部无歧义 DTO，再让业务层只接收转换后的单值字段。

常见问题

重复成员报错是不是 Go struct 写错了？

不一定。若原始 JSON 文本已经出现两个同名成员，错误发生在 JSON token 层；只有当输入没有重复名、但嵌入字段或标签生成同名输出时，才需要重点检查 Go 类型定义。

可以一直传 AllowDuplicateNames(true) 吗？

不建议。该选项是明确的兼容取舍，会让结果依赖成员处理顺序。只在已知上游协议、可控适配范围和充分回归测试的前提下局部使用。