Go encoding/json/v2 怎样选择严格重复键处理策略完成一个可复用的最小示例

我第一次把 Go 1.27 的 encoding/json/v2 接到旧接口时，最容易误判的不是字段映射，而是“同名键到底算不算一个合法输入”。v2 默认拒绝 JSON 对象里的重复名称；这个默认值更适合跨服务协议，因为调用方不必猜测后出现的值会覆盖、合并还是被忽略。

这篇只解决一个具体任务：新接口怎样保持严格拒绝，旧协议确实依赖重复名称时又怎样把放宽策略限制在一个清楚的调用点。Go 官方文档说明，兼容开关是 jsontext.AllowDuplicateNames(true)，它同时影响编码和解码；允许重复名称会让对象成员顺序变得可观察，不应成为业务语义。

默认使用 v2 的严格行为；只有已经确认上游协议允许重复名称，并且调用方接受其合并语义时，才显式传入 jsontext.AllowDuplicateNames(true)。

先界定重复键为什么值得单独处理

下面的输入在语法上看起来像普通对象，但 role 出现了两次：

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

问题在于 JSON 规范没有替应用程序规定重复名称的统一解释。不同组件可能取最后一个值、合并对象，或者直接报错。如果认证服务和业务服务的解释不同，同一份请求就可能产生不同的身份语义。v2 选择先拒绝，让这类歧义停在解码边界。

用一个函数保留严格错误边界

严格入口不需要额外的“拒绝重复键”参数，因为这是 v2 的默认行为。把错误识别封装起来，调用方就能区分重复名称和普通语法错误：

package main

import (
	"errors"
	"fmt"

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

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 {
		// 用官方哨兵错误识别重复名称，其他错误继续保留原始上下文。
		if errors.Is(err, jsontext.ErrDuplicateName) {
			return Request{}, fmt.Errorf("拒绝重复键: %w", err)
		}
		return Request{}, fmt.Errorf("JSON 解码失败: %w", err)
	}
	return req, nil
}

这里的重点不是把所有错误改写成一条中文消息，而是保留 %w 链。上层可以继续用 errors.Is 判断重复名称，也可以把原始错误记录到日志。对于普通的缺少逗号、字符串未闭合等问题，函数不会把它们误报成重复键。

只在兼容场景显式允许重复名称

如果旧设备或既有文件格式已经把重复名称当成输入约定，可以在适配层明确放宽：

func decodeLegacy(data []byte) (Request, error) {
	var req Request
	// 仅在已确认的旧协议适配层放宽检查，不把兼容行为变成全局默认。
	err := json.Unmarshal(data, &req, jsontext.AllowDuplicateNames(true))
	if err != nil {
		// 即使允许重复名称，语法错误和类型错误仍然必须返回给调用方。
		return Request{}, fmt.Errorf("旧协议 JSON 解码失败: %w", err)
	}
	return req, nil
}

允许后，成员会按观察到的顺序处理，后来的值可能替换或合并先前的值，具体结果取决于目标 Go 类型。这个函数适合放在“旧协议适配”包里，不适合被所有新接口直接复用。尤其不要因为某个上游偶尔发出重复键，就把整个服务的默认策略改成允许。

把选择写进迁移和测试边界

从旧的 encoding/json 迁移时，可以按三个问题做决定：

测试时至少覆盖一份正常对象、一份重复名称对象和一份普通语法错误。重复名称测试检查 errors.Is 能命中 jsontext.ErrDuplicateName；兼容测试则只确认适配函数能处理既有输入，并把这个选择写在函数名或包边界中。

还要留意另一个容易混淆的点：jsontext.AllowDuplicateNames(true) 只控制重复名称，不会替你放宽未知字段、大小写匹配或非法 UTF-8。迁移时不要把多个兼容选项一次性打开，否则很难知道是哪条旧语义在继续支撑系统。

常见问题

v2 能不能把重复键改成“取最后一个”？

可以显式允许重复名称后获得兼容行为，但不应把“最后一个”当成跨系统可靠协议。官方文档明确提醒，允许重复名称会使成员顺序变得可观察；更稳妥的做法是修正上游数据或在适配层完成一次性转换。

旧的 encoding/json 代码必须立刻重写吗？

不必。Go 1.27 继续支持原有 encoding/json API；迁移应先盘点重复名称、大小写匹配和未知字段等行为，再为需要更严格互操作性的接口单独采用 v2。

最终可以把规则记成一句话：新边界默认拒绝，旧边界局部放宽，错误分类保留原因，业务代码不依赖重复键的顺序。