Go JSON v2 和旧 encoding/json 怎样在同一服务中渐进迁移

可以在同一 Go 服务中用导入别名同时保留 encoding/json 与 encoding/json/v2，按接口选择编码入口。旧接口继续使用 v1，过渡接口可在 v2 调用中传入 jsonv1.DefaultOptionsV1()，已明确新契约的接口再采用 v2 默认值。不要把“换包”和“改字段语义”合并成一次全局替换。

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

现象：能编译，但返回字段发生变化

典型迁移问题不是包名冲突，而是同一 DTO 的零值、省略规则和 nil 集合编码发生变化。比如一个历史接口以“count 缺失”表达默认状态，新调用却把 count:0 输出出来，旧客户端可能采用不同分支。

Go 官方已在 JSON 介绍的更新说明中指出，Go 1.27 让 v2 与 jsontext 普遍可用。本文以该工具链能力为前提，不继续把旧实验文章中的开关要求机械套给所有版本。维护较早工具链时，应按对应版本文档处理实验支持；不要仅靠改 import 假定可以编译。

分层检查：先把路由、DTO 和编解码器分开

给两个包使用 jsonv1、jsonv2 别名，只解决源码命名。真正的迁移边界是旧路由、新路由、DTO 字段契约与编码入口之间的对应关系。把这些关系集中在少量适配函数，避免业务函数各自散落选项。

同一个服务可以共存两种语义，但同一接口不宜根据偶然调用路径选择默认值。迁移开关应绑定接口或明确的适配层，不应藏在全局可变状态中。

证据判断：字段标签与调用选项分别控制什么

v2 的 omitempty 按 JSON 空值语义判断，数字 0 和布尔 false 不属于空 JSON 值；omitzero 则面向 Go 零值。它们不能简单互换。共享 DTO 的标签修改会影响所有使用者，应与调用入口迁移分开审阅。

DefaultOptionsV1 是一组兼容语义选项，适合先迁移调用形式，再逐项改变行为。后面的选项可覆盖前面的设置，因此统一适配函数能减少“同一选项在多处被覆盖”的困惑。

修复动作：提供三个明确的编码入口

下面是独立 main.go 示例，只演示响应编码，不包含真实路由和线上流量。本例未在本文工作区运行，不把预期语义写成实际测试回执。

package main

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

type Reply struct {
    // 共享 DTO 先保持现有标签，暂不同时修改字段契约。
    Count int      `json:"count,omitempty"`
    Items []string `json:"items"`
}

// encodeLegacy 固定旧接口行为，供旧路由继续使用。
func encodeLegacy(v Reply) ([]byte, error) {
    return jsonv1.Marshal(v)
}

// encodeBridge 切换调用入口，但显式保留 v1 语义。
func encodeBridge(v Reply) ([]byte, error) {
    return jsonv2.Marshal(v, jsonv1.DefaultOptionsV1())
}

// encodeNew 仅供已明确接受 v2 字段语义的新接口使用。
func encodeNew(v Reply) ([]byte, error) {
    return jsonv2.Marshal(v)
}

func main() {
    value := Reply{}
    encoders := []struct {
        name string
        fn   func(Reply) ([]byte, error)
    }{
        {"legacy", encodeLegacy},
        {"bridge", encodeBridge},
        {"new", encodeNew},
    }
    for _, encoder := range encoders {
        b, err := encoder.fn(value)
        if err != nil {
            log.Fatalf("%s 编码失败：%v", encoder.name, err)
        }
        fmt.Printf("%s: %s\n", encoder.name, b)
    }
}

按本例零值 Reply 的契约，legacy 与 bridge 保留旧的 count 省略及 items 为 null 的行为；new 使用 v2 默认语义，count 的零值仍会输出，nil items 采用空数组表示。判断差异时关注字段存在性、类型与值，不依赖 JSON 对象成员的文本顺序。

输入解码应另设适配入口，不能因为输出编码通过就同时切换 Unmarshal。旧请求中的字段大小写、重复成员、null 与非零目标值合并行为，以及自定义 UnmarshalJSON，都需要独立考虑。发现 v2 拒绝某输入时，不建议静默回退到更宽松解析器，否则接口实际接受范围会变得难以解释。

反向确认：为一个接口写清楚回退范围

渐进迁移可先保留旧入口，过渡入口保留 v1 语义，再为一个明确的新接口采用 v2 默认行为。每次只改变一项契约：例如先决定零值字段是否保留，再决定 nil 集合是否转为空集合。

读者接入项目时，可用固定样本比较旧入口与过渡入口的业务语义，再检查新入口的预期差异。样本至少覆盖零值、空集合、nil、字段省略和已有自定义方法。这里给出的是项目迁移建议，本文没有运行这些测试。

回退编码入口只能恢复编解码选择，不能撤销已经写入数据库、缓存或消息队列的新格式。若响应内容还用于签名或缓存键，必须额外明确字节表示要求，不能拿一般 JSON 语义等价替代字节一致。

迁移清单与常见问题

• 固定工具链前提，不混淆早期实验文档与当前包能力。
• 用导入别名共存，按接口绑定适配函数。
• 先保留字段标签，分别审阅选项与 DTO 变化。
• 编码与解码分开推进，显式处理错误。
• 记录回退影响范围，避免隐式宽松解析兜底。

启用新工具链会让旧接口自动变成 v2 语义吗？

不应把实现内部变化和公开 API 语义混为一谈。继续调用 encoding/json 的接口仍以兼容行为为契约，选择 v2 包才应明确其默认差异。

可以永久使用 DefaultOptionsV1 吗？

可以将它作为兼容边界保留，但应写明原因。使用 v2 入口并不意味着必须一次性接受所有新默认值。

只改成 omitzero 就完成迁移了吗？

没有。它只涉及字段省略的一部分，集合表示、解码规则和自定义方法仍有独立边界。

参考：当前 JSON API 介绍 https://go.dev/blog/jsonv2；v1 兼容选项 https://pkg.go.dev/encoding/json#DefaultOptionsV1；v2 字段规则 https://pkg.go.dev/encoding/json/v2。