Go JSON 重复字段处理差异的兼容清单

同一段 JSON 如果把一个字段写了两次，Go 服务可能出现两种完全不同的兼容结果：传统的 encoding/json v1 默认接受重复成员名，较后出现的值会覆盖或并入先前的值；encoding/json/v2 默认拒绝重复名。接口升级时如果只替换 import，却没有把这条差异写进兼容清单，就可能让网关、旧服务和新服务对同一请求得出不同对象。

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

v2 参考：https://pkg.go.dev/encoding/json/v2

处理重复字段的第一原则是先决定输入契约：旧接口必须兼容时保留 v1 语义并记录风险；新接口需要明确拒绝时使用 v2 默认行为或在解码前做重复名检查。DisallowUnknownFields 只管未知字段，不能替代重复字段检查。

先把兼容基线写成行为矩阵

JSON 标准没有给重复成员名规定一个跨实现都相同的解释，因此不能把“最后一个赢”当作所有解析器的通用规则。Go 官方文档把 v1 和 v2 的差异写得很清楚：v1 默认允许重复名，v2 默认拒绝；v2 还提供 jsontext.AllowDuplicateNames 作为显式兼容开关。

v1 为什么容易出现“后值覆盖”的错觉

用传统入口解码到 struct 时，输入成员会按出现顺序处理。简单标量字段第二次赋值通常会覆盖第一次；如果目标是 map，后来的同名键也会替换已有键。对于 struct、map、slice、指针或嵌套对象，具体结果还会受到“解码到已有值时是否合并”的类型语义影响，所以不能只记一句“永远最后一个赢”。

package main

import (
	"encoding/json"
	"fmt"
)

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

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

	// v1 接受重复成员名；这里用结果展示兼容风险，不把顺序当成业务规则。
	if err := json.Unmarshal(data, &req); err != nil {
		fmt.Println("decode error:", err)
		return
	}
	fmt.Println(req.Role)
}

这段代码的重点不是把第二个值当成“正确答案”，而是提醒维护者：如果鉴权、价格或状态字段允许重复出现，业务层拿到的对象已经丢失了“曾经出现过多个值”的信息。要保留这个证据，检查必须发生在普通对象解码之前。

把“严格”拆成两件不同的事

第一件是未知字段：旧版 encoding/json.Decoder 默认忽略目标 struct 不认识的字段，可以按需调用 DisallowUnknownFields。第二件是重复字段：这个选项并不负责检测同名成员，字段名即使是已知的，重复仍然是另一类输入问题。

如果项目采用 v2，可以让默认拒绝重复名成为输入层契约；如果项目还必须接受上游旧格式，则应明确把兼容选项限制在边界适配器里，不要让整个业务层都依赖重复字段的顺序。

package main

import (
	"encoding/json/v2"
	"encoding/json/jsontext"
	"fmt"
)

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

func decodeStrict(data []byte) (Request, error) {
	var req Request

	// v2 默认拒绝重复名；错误应在进入业务对象前返回给调用方。
	if err := json.Unmarshal(data, &req); err != nil {
		return Request{}, err
	}
	return req, nil
}

func decodeLegacyCompatible(data []byte) (Request, error) {
	var req Request

	// 只有明确兼容旧上游时才打开该开关，并把范围收窄到适配函数。
	if err := json.Unmarshal(data, &req, jsontext.AllowDuplicateNames(true)); err != nil {
		return Request{}, err
	}
	return req, nil
}

func main() {
	_, err := decodeStrict([]byte(`{"role":"reader","role":"admin"}`))
	fmt.Println(err)
}

如果当前 Go 工具链或项目依赖还不能使用 v2，则不要为了“看起来严格”自行改写 encoding/json 的内部逻辑。可以把输入保留为字节流，在适配层使用经过维护的重复名检测器，或者先按 JSON token 扫描对象层级，再交给既有解码器；关键是让策略在边界处可见、可替换、可测试。

迁移时按接口列出四个检查项

1. 来源是否可控：内部服务、第三方 webhook、历史客户端分别记录，不要用一个全局开关覆盖所有来源。
2. 重复字段是否有业务风险：身份、金额、权限、状态等字段优先拒绝；普通扩展字段才考虑兼容适配。
3. 旧服务和新服务是否混用：在灰度期间记录拒绝计数和原始请求的安全摘要，确认上游已停止发送重复名后再收紧。
4. 兼容开关是否可回收：用接口级配置或适配器封装，迁移完成后删除开关，避免它变成永久的隐式协议。

这里的“计数”是运维检查项，不代表本文对某个线上服务给出压测结果。指标驱动的价值在于把“兼容没问题”拆成可观察的请求数量、拒绝数量、来源分布和回滚条件。

最容易混淆的三个边界

• 重复名不等于未知字段：role 出现两次仍然是已知字段，DisallowUnknownFields 不会替你拒绝它。
• 大小写匹配也会影响判断：v1 默认接受大小写不敏感的 struct 字段匹配；如果不同拼写最终命中同一个字段，迁移时要单独记录，不要把它误写成重复文本键的唯一规则。
• 客户端先规范化会丢证据：某些代理或中间件可能在转发前合并对象成员。需要追查重复输入时，检测点要尽量靠近原始请求边界。

结论：让重复字段策略成为接口契约

兼容清单可以压缩成一句话：v1 适合承接历史输入，但重复名的结果不能当作稳定业务协议；v2 默认拒绝，更适合新接口把输入错误尽早暴露；必须兼容时，用显式的 AllowDuplicateNames(true) 或边界适配器隔离旧语义。最后再用接口级指标确认迁移是否完成，而不是凭一次成功解码就宣布兼容。

相关问题

Go 的 DisallowUnknownFields 能拒绝重复 JSON 字段吗？

不能。它只针对目标 struct 没有匹配字段的输入；重复字段需要 v2 默认拒绝、显式选项或独立的输入层检测。

重复字段一定是后一个值覆盖前一个吗？

不能一概而论。v1 按输入顺序处理，标量常见表现是后值覆盖，但不同目标类型和嵌套对象可能出现合并语义。

旧接口必须兼容时应该全局开启 AllowDuplicateNames 吗？

不建议。把开关限制在明确的上游适配入口，并为高风险字段保留拒绝或迁移计划，避免兼容行为扩散到所有接口。