jsonv2严格处理重复对象键

如果接口输入里出现两个同名 JSON 对象键，旧版 encoding/json 往往会继续解析，后出现的值可能覆盖或合并前面的值；encoding/json/v2 默认把它当成错误。处理这类输入时，入口应保留 v2 的严格语义，只有在已经确认协议依赖重复键时，才对特定调用显式放开。

官方文档：https://pkg.go.dev/encoding/json/v2

官方介绍：https://go.dev/blog/jsonv2

先判断重复键是不是协议问题

重复键的危险不在于 JSON 文本一定无法解析，而在于不同实现可能选择保留第一个值、保留最后一个值、合并对象或直接拒绝。这样一来，鉴权层看到的请求和业务层实际使用的请求可能不是同一个语义。Go 官方对 v2 的设计说明也把拒绝重复名作为更严格的默认行为；这与 RFC 8259 对重复名未规定唯一解释有关。

用 v2 默认语义拒绝重复对象键

新代码直接调用 encoding/json/v2 的 Unmarshal 即可。下面的代码把重复键放在“输入边界”处理：普通 JSON 进入结构体，重复键则在进入业务逻辑前返回错误。示例包含了 goexperiment.jsonv2 构建标签，实际采用时应按当前 Go 发行版的实验特性说明准备构建环境。

//go:build goexperiment.jsonv2

package main

import (
    "errors"
    "fmt"

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

type Request struct {
    UserID string `json:"user_id"`
}

func decodeRequest(data []byte) (Request, error) {
    var req Request
    // v2 默认拒绝同一个对象内重复的 JSON 成员名。
    if err := jsonv2.Unmarshal(data, &req); err != nil {
        // 只把重复名归类为输入问题，其他语法或类型错误继续保留原错误。
        if errors.Is(err, jsontext.ErrDuplicateName) {
            return Request{}, fmt.Errorf("request contains duplicate object name: %w", err)
        }
        return Request{}, fmt.Errorf("decode request: %w", err)
    }
    return req, nil
}

这里没有手动扫描字符串，也没有先解码成 map[string]any 再判断。重复名检测属于 JSON 文本层的语法约束，交给 v2 可以避免业务结构体、鉴权代码和日志代码各自采用一套规则。

把重复键位置写进排障日志

仅记录“解析失败”对值班排障不够。jsontext.SyntacticError 会携带字节偏移和 JSON Pointer；当底层错误是 ErrDuplicateName 时，可以从 Pointer 的最后一个 token 取出重复的键名。

func duplicateNameDetail(err error) (string, bool) {
    var syntaxErr *jsontext.SyntacticError
    // As 把包装后的错误还原为 JSON 文本层的结构化错误。
    if !errors.As(err, &syntaxErr) || syntaxErr.Err != jsontext.ErrDuplicateName {
        return "", false
    }

    // JSON Pointer 指向发生重复的对象成员，最后一个 token 就是键名。
    return syntaxErr.JSONPointer.LastToken(), true
}

func classifyDecodeError(err error) string {
    // 日志分类只依赖稳定的哨兵错误，不依赖易变化的错误文本。
    if name, ok := duplicateNameDetail(err); ok {
        return fmt.Sprintf("duplicate-json-name:%s", name)
    }
    return "other-json-decode-error"
}

日志里可以同时保存错误类别、键名和上游请求标识，但不要把完整的敏感 JSON 原文直接打出来。Pointer 适合帮助定位结构位置，不能替代访问控制和请求脱敏。

兼容旧协议时只在适配层放开

如果上游协议明确允许重复键，并且你已经接受“后出现的成员可能替换或合并前值”的语义，可以在调用点传入 jsontext.AllowDuplicateNames(true)。这个选项同时影响编码和解码；它不是只让解码器忽略一次错误，也不应被塞进全局共享配置。

func decodeLegacyPayload(data []byte) (map[string]any, error) {
    var payload map[string]any
    // 仅旧协议适配入口允许重复名，避免新接口继承宽松语义。
    if err := jsonv2.Unmarshal(data, &payload, jsontext.AllowDuplicateNames(true)); err != nil {
        // 即使已允许重复名，其他 JSON 语法和类型错误仍然要返回。
        return nil, fmt.Errorf("decode legacy payload: %w", err)
    }
    return payload, nil
}

适配层最好带有来源标记、协议版本和下线计划。若只是为了兼容 v1 的其他行为，不必一次性切回全部旧语义；官方迁移说明支持通过选项逐项选择行为。重复名允许、大小写匹配和未知成员接受应分别评估。

上线前保留三条检查线

• 入口 JSON：默认拒绝重复键，并把 ErrDuplicateName 归为客户端输入或协议违规。
• 兼容入口：只有明确的旧协议适配器使用 AllowDuplicateNames(true)，且记录来源与退出条件。
• 策略边界：不要把重复键、大小写匹配、未知字段和编码输出混成一个“宽松模式”。

这样处理后，jsonv2严格处理重复对象键 的核心就很明确：默认让输入语义唯一；需要兼容时，把例外限制在可追踪的边界，并保留结构化错误信息供日志和回滚使用。

常见问题

jsonv2 发现重复键时会保留最后一个值吗？

默认不会进入“保留哪个值”的业务语义，而是返回重复对象名错误。只有显式允许重复名后，才会按对象成员出现顺序处理，具体合并效果还取决于目标 Go 类型。

AllowDuplicateNames(true) 只影响 Unmarshal 吗？

不是。它是 jsontext 的通用选项，同时影响编码和解码；因此生成 JSON 的自定义编码路径也应保持同样的协议边界。

“foo”和“Foo”算重复键吗？

v2 默认按大小写敏感名称匹配。若另外启用 jsonv2.MatchCaseInsensitiveNames(true)，大小写变化可能匹配同一个结构体字段，并参与重复名检测；这应作为独立的兼容决策。