Go encoding/json/v2 试用时的行为差异梳理

如果你准备在 Go 1.27.x 中试用 encoding/json/v2，先记住一个结论：它不是把导入路径替换掉就能得到完全相同结果的 v1。v2 的默认值更偏向严格、可互操作的 JSON；字段名匹配、nil 容器、重复键和非法 UTF-8 都可能改变旧程序的输入接受范围或输出快照。

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

先确认 v2 的试用入口与兼容范围

Go 1.27 的标准库新增了 encoding/json/v2 和较底层的 encoding/json/jsontext。前者提供带可变 Options 的 Marshal、Unmarshal 以及读写流接口，后者负责 JSON token 和语法层处理。v1 API 没有被删除，旧代码不需要一次性迁移；真正需要谨慎的是：同一组结构体和输入，切换包名后默认语义不一定相同。

建议先把试用代码放在独立包或回归分支中，固定 Go 工具链和 JSON 样本。不要把“编译通过”当作兼容完成，因为很多差异只会在字段名、空值或异常输入出现时暴露。

四个默认差异最容易改变什么

下面四类差异最值得先测。它们不是性能结论，而是协议边界变化：

这也解释了为什么“只替换 import”风险较高：接口响应快照可能从 null 变成 []，而网关传来的重复键或坏 UTF-8 则可能从可解析变为错误。未知字段仍默认忽略；如果业务要求输入字段必须全部被识别，还要显式启用 RejectUnknownMembers。

用 Options 把兼容策略写进代码

兼容不要靠注释约定，直接落在调用点或字段标签上。下面的例子只演示“兼容大小写字段”这一条策略，其他策略按同样方式组合：

package main

import (
    "fmt"
    "log"

    "encoding/json/v2"
)

func main() {
    // case:ignore 只作用于这个字段，优先保留精确名称匹配。
    var dst struct {
        UserName string `json:"userName,case:ignore"`
    }
    input := []byte(`{"Username":"lin"}`)
    if err := json.Unmarshal(input, &dst); err != nil {
        // 生产代码应把错误连同请求标识记录，而不是静默吞掉。
        log.Fatal(err)
    }
    fmt.Println(dst.UserName)
}

如果是全局策略，可使用包提供的 Options；如果只是一两个旧字段需要兼容，字段级标签更容易控制影响面。nil slice/map 可以选择 FormatNilSliceAsNull 或 FormatNilMapAsNull，重复键和非法 UTF-8 则对应 jsontext.AllowDuplicateNames、jsontext.AllowInvalidUTF8。这些选项的含义要写入协议说明，否则后续维护者很难判断它是临时兼容还是永久约定。

切换前后用四组样本做回归

建议把以下样本放进表驱动测试：大小写不同但语义相同的字段；nil 与空 slice/map；包含重复 JSON 名称的原始字节；带非法 UTF-8 的字符串。对每组样本同时记录是否报错、结构体结果、输出 JSON 和错误类型，不要只比较最终 HTTP 状态码。

还要单独检查 omitempty、omitzero、数组长度、time.Duration、自定义 Marshaler，以及 map 输出顺序。v2 允许通过选项获得部分 v1 语义，但“兼容开关”不是协议升级的替代品。若 Go 1.27 的新实现确实与现有依赖冲突，可在构建阶段临时使用 GOEXPERIMENT=nojsonv2 回退旧实现，并把回退原因记录到升级单中。

相关问题

encoding/json/v2 能直接替代 encoding/json 吗？

不能按无差别替换理解。API 形状相近，但默认语义、选项和错误边界都有差异，应先做样本回归。

v2 为什么拒绝重复 JSON 名称？

重复名称会让不同实现对同一对象产生不同解释。v2 默认拒绝它，减少认证、解析和业务执行阶段的语义分歧。

什么时候保留 v1 语义？

当外部协议明确依赖 null、大小写宽松或历史脏输入时，可以先用局部 Options 过渡，再推动上游数据和契约收敛。