Go JSON 重复字段为什么得到不同结果

Go 里遇到 JSON 重复字段，结果通常不是随机的，而是由三个条件共同决定：使用的是哪套 JSON 实现、目标是 map 还是 struct、后面的字段是否继续落到同一个嵌套对象。标准库文档明确说明，encoding/json v1 会按输入顺序处理对象成员，后出现的重复字段可能替换或合并前面的值。

先确认：你比较的是同一份 JSON 和同一个目标吗

排查这类问题时，第一步不是修改字段标签，而是把原始字节、解码目标和读取位置分别记下来。比如下面的 JSON 同时包含两个 code 字段，它本身仍可能被 v1 接受，但最终表现要看目标类型。

{
  "code": 200,
  "code": 500,
  "message": "ready"
}

如果日志只打印了 struct，却拿它和另一处保存的原始 map 比较，很容易误以为“同一个字段解析出了两个结果”。实际上，两个目标各自保存了一份解码结果；先确认输入字节没有被中间层改写，再确认两处读取的确实是同一个字段。

为什么 map 和 struct 会得到不同结果

map 的键和值是一对一写入的，同名键再次出现时，后来的值会写到同一个键上。struct 则要先经过字段名或 json 标签匹配，再把值交给具体字段解码；当重复字段是对象时，后一个对象的成员可能继续合并到已有 struct 字段。

下面这个最小示例把同一份 JSON 解码到 map 和 struct。代码注释只说明排查重点，不代表在文章配图中执行过。

package main

import (
	"encoding/json"
	"fmt"
)

type Profile struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

func main() {
	raw := []byte(`{"code":200,"code":500,"message":"ready"}`)

	var asMap map[string]any
	var asStruct Profile
	// 同一份原始 JSON 分别进入 map 和 struct，方便对照目标类型。
	mapErr := json.Unmarshal(raw, &asMap)
	structErr := json.Unmarshal(raw, &asStruct)
	if mapErr != nil || structErr != nil {
		// 先打印错误，避免把解码失败误判成重复字段的语义差异。
		fmt.Printf("mapErr=%v structErr=%v\n", mapErr, structErr)
		return
	}
	// v1 的同名标量字段按输入顺序处理，后出现的 500 会覆盖 200。
	fmt.Printf("map=%v struct=%+v\n", asMap, asStruct)
}

这段代码的关键不是打印格式，而是两个目标都由同一份 raw 产生。若一个目标得到 200、另一个得到 500，优先检查是否实际使用了不同的 JSON 包、不同的输入副本，或者某个目标带有自定义 UnmarshalJSON。

嵌套对象为什么看起来像“合并”

重复字段不一定是简单覆盖。对于 struct 目标，如果重复成员的值也是 JSON 对象，解码过程会继续进入已有的嵌套字段。例如第一段给出 region 和 zone，第二段只给出新的 region，最终可能看到新的区域值仍保留旧的 zone。

type Config struct {
	Meta struct {
		Region string `json:"region"`
		Zone   string `json:"zone"`
	} `json:"meta"`
}

func decodeConfig(raw []byte) (Config, error) {
	var cfg Config
	// 两个 meta 对象关注不同成员，用于观察嵌套字段的合并表现。
	err := json.Unmarshal(raw, &cfg)
	return cfg, err
}

// raw 示例：{"meta":{"region":"cn","zone":"a"},"meta":{"region":"us"}}
// v1 中可观察到 region 使用后值，而 zone 仍可能保留前一对象的值。

因此，看到“后一个对象没有提供的字段仍然存在”时，不要只按最后一个 JSON 对象整体替换来推断。还要看目标是 struct、字段是否已有内容，以及是否存在自定义解码逻辑。若业务要求每次对象都完全替换，应该在进入解码前清空目标，或改用能明确表达替换语义的处理方式。

大小写和字段标签也会改变判断结果

encoding/json v1 先偏好精确匹配，但也接受大小写不敏感的字段名匹配。于是 "name"、"Name" 和带有 json:"name" 标签的 struct 之间，不能只看 Go 字段的首字母来推断落点。调试时建议把实际标签和原始 JSON 键一起打印出来，尤其要留意中间层是否把键名规范化。

v1 与 v2 的处理方式不是一回事

当前 Go 官方文档把 encoding/json 说明为保留历史行为的 v1 包，并列出了 encoding/json/v2 的差异：v1 允许 JSON 对象出现重复名称；v2 默认会因为重复名称返回错误，同时默认使用更严格的大小写匹配规则。AllowDuplicateNames 是 v2 中控制重复名称行为的选项。

这解释了为什么同一份输入在升级依赖或切换实现后出现不同结果：变化的不一定是 JSON 文本，也可能是解析器默认选项。兼容旧接口时先固定 v1 语义；新接口若不接受重复字段，则应在边界层选择 v2 的严格行为并把错误交给调用方处理。

一份可复用的排查清单

1. 记录原始 JSON 字节，不要只记录已经解码的对象。
2. 确认导入路径，区分 encoding/json 与 encoding/json/v2。
3. 把同一份输入分别解码到 map、简单 struct 和嵌套 struct，观察差异在哪一层出现。
4. 检查字段标签、大小写、指针字段和自定义 UnmarshalJSON。
5. 明确业务要的是“最后值覆盖”“嵌套字段合并”还是“重复即报错”，再选择实现和测试断言。

常见问题

JSON 重复字段是不是一定非法

不能一概而论。encoding/json v1 会接受这类输入并按历史规则处理；官方文档列出的 v2 默认行为则是重复名称报错。

为什么 map 和 struct 结果不一样

map 只做键值写入，struct 还要经过字段匹配和目标字段解码；嵌套对象进入 struct 后还可能出现字段级合并。

只保留最后一个值安全吗

只有当业务明确允许重复字段并且重复顺序可信时才适合。对配置、权限或签名相关输入，更稳妥的是在解析边界拒绝重复名称，避免调用方和下游对同一请求产生不同解释。