Go encoding/json/v2 对象重复字段被拒绝怎么办

如果你用encoding/json/v2解析JSON对象时碰到重复字段直接被报错拒绝的情况，不需要回退到旧版v1的实现，调整对应解析配置就能按需兼容。

我第一次把 Go 1.27 的 encoding/json/v2 接到旧接口时，最先看到的不是字段映射错误，而是“对象成员名重复”。排查后发现，问题在输入 JSON：同一个成员名出现了两次。v2 默认拒绝这种语义不明确的 JSON；我的处理顺序是先修上游，只有历史数据无法立即清洗时，才在一个明确的调用点传入 jsontext.AllowDuplicateNames(true)。

不要为了让请求“先跑起来”就默认接受重复字段。认证层、网关和业务层对“重复字段取前一个还是后一个”可能有不同理解，严格拒绝可以先把这种歧义暴露出来。

• 新协议：修正生产 JSON，让每个对象成员名只出现一次。
• 兼容协议：只对已知的历史输入开启 AllowDuplicateNames(true)，不要把它设成全局习惯。
• 语义边界：允许重复后，成员按输入顺序处理，后面的值可能替换或合并前面的值，取决于目标 Go 类型。

先确认现象：拒绝来自重复成员名

JSON 对象在语法上由名称和值组成，但标准没有规定重复名称应该采用哪个值。v1 的 encoding/json 默认允许重复名称，v2 则选择更严格、互操作性更好的默认值：重复成员名直接产生错误。这样做是为了避免不同服务在同一份请求上得出不同结果。

我排查时先记录原始 JSON 的成员名，再看是否额外开启了 MatchCaseInsensitiveNames。因为开启大小写不敏感匹配后，user 和 User 也可能匹配同一个 Go 结构体字段，进而参与重复名称判断。这个证据能把“字段标签写错”和“输入语义重复”区分开。

修复路径一：先改上游，再保持严格默认

新接口优先修正生成方或拼接方，把同一个对象中的重复键合并成一个明确字段。下面保留 v2 的严格默认：当输入出现两个 role 时，程序把错误交给调用方，而不是擅自选择后一个值。

package main

import (
	"fmt"

	json "encoding/json/v2"
)

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

func main() {
	// 这个输入故意包含两个 role，用来展示 v2 的严格默认行为。
	raw := []byte(`{"user":"alice","role":"reader","role":"admin"}`)

	var req Request
	if err := json.Unmarshal(raw, &req); err != nil {
		// 生产代码应把原始输入、请求编号等信息写入安全日志，
		// 不要把未经处理的敏感 JSON 直接回显给客户端。
		fmt.Println("解码失败：", err)
		return
	}

	fmt.Printf("%+v\n", req)
}

示例的预期现象是进入错误分支，而不是得到一个可以依赖的 Role 值。修复上游时，应在生成 JSON 的 DTO、字段合并逻辑或代理转发层定位重复来源；不要只在业务层把错误吞掉。

修复路径二：历史数据才局部放宽

如果旧系统已经产生重复成员名，而且迁移期间必须继续接收，可以把兼容策略写在一次具体的解码调用上。AllowDuplicateNames(true) 来自 encoding/json/jsontext，它可以作为 v2 的选项传入；该选择同时改变编码或解码时的重复名称检查。

package main

import (
	"fmt"

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

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

func main() {
	// 只在已经确认的历史兼容边界使用这个选项，不要作为全局默认。
	raw := []byte(`{"user":"alice","role":"reader","role":"admin"}`)

	var req Request
	err := json.Unmarshal(raw, &req, jsontext.AllowDuplicateNames(true))
	if err != nil {
		// 即使允许重复，格式错误和目标类型不匹配仍然需要处理。
		fmt.Println("兼容解码失败：", err)
		return
	}

	// 允许重复时按输入顺序处理；不要把这里的结果当成协议规范。
	fmt.Printf("兼容结果：%+v\n", req)
}

对于结构体目标，后出现的同名成员通常会影响同一个字段的最终值，但这不是应该写入协议的“取最后一个”规则。官方文档还说明，重复成员可能按目标 Go 值类型发生替换或合并；如果业务需要保留每一次出现的顺序，应改用更适合表示有序成员的结构，而不是把结构体解码结果当作审计记录。

复查清单：兼容开关留下什么边界

允许重复后一定取最后一个值吗？

不能把它概括成稳定的“最后一个覆盖前一个”。v2 文档说明成员按观察到的顺序处理，后面的值可能替换或合并前面的值，具体取决于目标 Go 类型。若协议要求确定语义，应先清理输入或定义专门的有序数据结构。

role 和 Role 算不算重复？

默认情况下，v2 使用大小写敏感的名称匹配；如果显式开启 MatchCaseInsensitiveNames，大小写变化也可能匹配同一个结构体字段，从而影响重复检测。不要只根据字段名的视觉差异判断结果。

为了兼容旧 JSON，必须放弃 encoding/json/v2 吗？

不必。可以只在兼容旧数据的调用点传入 jsontext.AllowDuplicateNames(true)，其它新接口继续使用严格默认。Go 1.27 仍然支持原来的 encoding/json API，是否迁移应按输入协议和兼容成本决定。