Go 1.27 JSON v1 与 v2 渐进切换：Options 如何控制兼容语义

服务升级到 Go 1.27 后，encoding/json 不会突然变成另一套行为：旧的 v1 API 仍然保留，而且底层已经由 v2 实现配合兼容选项支撑。真正需要设计的是迁移节奏——先让新入口输出与旧入口一致，再一次只切换一种语义，才能知道回归差异究竟来自字段匹配、omitempty，还是 nil 容器和重复字段。

先把三个 JSON 入口的职责分开

Go 1.27 正式提供 encoding/json/v2 与较低层的 encoding/json/jsontext。v2 的 Marshal、Unmarshal 比 v1 多一组可变参数 Options，因此调用方可以明确选择兼容行为。v1 则继续保持历史默认值，官方说明也明确承诺它会继续受支持。

这三者不是“旧包废弃、新包接管”的简单替换关系。迁移时最有用的能力，是 v1 和 v2 的 Options 可以组合：先引入 v2 调用入口，却仍使用完整的 v1 默认选项，随后再按风险逐项覆盖。

用 DefaultOptionsV1 建立不改变行为的基线

第一步不是启用全部 v2 新语义，而是让新函数保持旧输出。下面的包装函数把调用入口换成 v2，但通过 DefaultOptionsV1 维持 v1 兼容语义：

package codec

import (
    jsonv1 "encoding/json"
    jsonv2 "encoding/json/v2"
)

func MarshalLegacy(v any) ([]byte, error) {
    return jsonv2.Marshal(v, jsonv1.DefaultOptionsV1())
}

这段代码适合作为迁移起点，因为它把“调用入口变化”和“序列化行为变化”拆开了。结构上可以理解为 encoding/json v1 API 把兼容语义集中到 DefaultOptionsV1，再交给 jsonv2 Marshal。先替换内部包装层并对已有样本做字节级或结构级对比；确认兼容后，再决定某个接口是否需要更严格的行为。

后置 Options 让单项语义先进入灰度

Options 的组合顺序很关键：后传入的同类选项覆盖前面的设置。于是可以先装入完整 v1 默认值，再把某一项切到 v2 规则。比如旧系统允许 JSON 对象出现重复名称，新规则希望直接拒绝，可以只调整这一项：

package codec

import (
    jsonv1 "encoding/json"
    jsonv2 "encoding/json/v2"
    "encoding/json/jsontext"
)

func UnmarshalStrictNames(data []byte, dst any) error {
    return jsonv2.Unmarshal(
        data,
        dst,
        jsonv1.DefaultOptionsV1(),
        jsontext.AllowDuplicateNames(false),
    )
}

这样做时，大小写匹配、空值合并、数组长度等其他行为仍沿用 v1，测试失败的归因范围很小。反过来也成立：新接口默认采用 v2，只给某个旧数据模型保留一项历史语义，例如 jsonv1.OmitEmptyWithLegacySemantics(true)。

迁移清单要围绕数据契约，而不是包名

官方迁移说明列出的差异很多，但业务最容易踩中的通常集中在四组。每组都应有自己的样本和验收标准：

• 字段匹配：v1 默认不区分大小写，v2 默认精确匹配；先统计线上是否存在大小写漂移的字段名。
• 空值表达：v2 对 omitempty 的定义更偏向编码后的 JSON 空值；布尔值、数字、指针和接口字段宜评估 omitzero。
• 容器表示：v1 把 nil slice/map 编码成 null，v2 默认倾向空数组或空对象；前端和签名系统可能把它们视为不同契约。
• 输入严格度：v2 默认拒绝非法 UTF-8 与重复对象名，能提前暴露脏数据，也可能让旧数据导入直接报错。

还要留意 map 输出顺序：v1 默认确定性排序，v2 默认不保证确定顺序。若 JSON 文本参与缓存键、签名或快照测试，不能只比较解码后的对象；要先明确文本顺序是不是协议的一部分。

一套紧凑的灰度策略

1. 把 JSON 调用集中到少量包装函数，记录哪些接口仍依赖 v1 行为。
2. 先改为 v2 函数加 DefaultOptionsV1，确认输出、错误类型和关键样本没有意外变化。
3. 从最能提升数据质量的一项开始，例如拒绝重复字段名；一次只覆盖一个 Option。
4. 同时保留结构级断言和文本级断言，避免 map 顺序、HTML 转义或 nil 表示改变后被单一测试漏掉。
5. 新接口直接采用 v2 默认值；旧接口按业务兼容窗口逐步收紧，不要求全仓库同一天切换。

Go 1.27 还保留了构建期开关 GOEXPERIMENT=nojsonv2，可在遇到实现兼容问题时暂时恢复原来的 v1 实现。但它是排障和回退手段，不应替代接口级的 Options 设计；官方也说明这个退出开关预计会在后续版本移除。

常见问题

升级到 Go 1.27 后必须导入 encoding/json/v2 吗？

不必。原来的 encoding/json 会继续受支持，默认行为仍保持 v1 语义。只有新代码或需要可控迁移的接口才需要主动采用 v2。

DefaultOptionsV1 是否等于继续调用 v1？

在语义目标上等价：官方文档说明 v1 的 Marshal 与 Unmarshal 本身就是通过 v2 加 DefaultOptionsV1 实现。迁移仍应核对错误文本，因为发布说明提示错误消息的具体文字可能变化。

为什么不直接给整个服务开启 DefaultOptionsV2？

因为字段匹配、nil 容器、map 顺序和重复字段会同时变化，出现回归时难以归因。按接口和数据契约逐项切换，更容易定位并回退。

新接口还需要保留任何 v1 Option 吗？

默认不需要。只有明确存在历史客户端、旧快照或外部协议约束时，才应保留对应的单项兼容设置，并在代码旁记录移除条件。

结语

Go 1.27 给 JSON 迁移留下了足够缓冲：旧 API 不会消失，新 API 又能通过 Options 精细控制。稳妥做法是先用 DefaultOptionsV1 把入口和行为拆开，再围绕字段匹配、空值、容器和输入严格度逐项灰度。这样每次变化都有明确边界，也能把回退从“换回整个包”缩小到一个选项。