Go json/v2 迁移时怎样评估兼容风险

评估 Go json/v2 迁移风险，重点不是新包能不能编译，而是原来的消费者是否仍然理解输入和输出。字段被忽略、null 变成空数组、零值字段重新出现，都可能在没有编解码错误的情况下改变业务。建议先保留旧语义，再按协议逐项启用新行为；权限请求和签名数据不能与普通展示接口共用一份粗略的“成功率”。

先锁定工具链和协议目标

本文以 Go 1.27 官方文档为基线。截至 2026 年 10 月，不能再把 Go 1.25 的实验开关说明当成现行迁移指南。Go 1.27 提供 json/v2，并让原 encoding/json 由 v2 实现支撑，但保留 v1 编解码行为；错误文本可能变化。继续使用旧包并不等于直接启用 v2 默认语义，也没有必须立即迁移的要求。

准备工作只需先写清三个对象：构建工具链版本、实际 import 路径、接口契约。记录生产者和消费者各自使用的解析器，以及 null、字段缺省、空集合和零值在业务中的含义。若当前仍用 Go 1.25 或 1.26，应查对应版本文档；不要把本文 Go 1.27 的 API 和标签直接照搬到旧环境。

官方发布说明：https://go.dev/doc/go1.27。以下代码是待读者在自己的隔离环境运行的示例，本文没有执行编译、回放或性能测试。

把兼容风险分成输入与输出两张清单

输入风险先看是否拒绝，再看是否解析成相同业务对象。v2 默认拒绝重复对象名称和无效 UTF-8，旧包通常允许重复名称或替换无效字节；重复名称的旧行为不应简单概括成“最后一个总是覆盖”，具体还可能与目标类型的合并行为有关。严格化有利于统一解释，但历史存量报文可能因此失败。

字段匹配尤其容易被漏掉：v2 默认区分大小写，而旧包允许不区分大小写的匹配。假设字段标签是 userID，上游发 userid，v2 默认可能将其视为未知字段。未知成员默认被忽略，因此“没有报错”仍可能得到零值。是否启用 RejectUnknownMembers 必须结合协议决定：封闭权限请求适合严格边界，可扩展事件则要考虑新增字段的前向兼容。

输出清单按消费者判断，而不是只看服务自己的测试：

要表达“Go 零值不输出”，可以评估 omitzero；不要机械地把所有 omitempty 换掉，空但非 nil 的集合与 nil 集合并不等价。Deterministic(true) 可用于确定性输出，但不等于跨工具链、跨平台的通用 JSON 规范化或签名协议。签名系统仍需明确规范化标准、转义规则及自定义序列化行为。

图示把输入解释和输出表示分开：解析成功只是输入条件之一，消费者对字段含义的理解才是兼容判断。

用兼容选项集中管理语义

把编码行为集中到协议适配层，比在每个业务函数临时加选项更容易控制。下面保留全部 v1 语义，随后只让普通 nil 切片采用空数组表示；其他旧行为仍保留，包括 nil map 的表示。示例不是“最安全设置”，而是一种控制变更范围的方式。

package contract

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

type Reply struct {
    Items []string `json:"items"`
    Enabled bool `json:"enabled,omitempty"`
}

func MarshalReply(v Reply) ([]byte, error) {
    // 以旧协议为基线，仅改变普通 nil 切片的表示。
    return jsonv2.Marshal(v,
        jsonv1.DefaultOptionsV1(),
        jsonv2.FormatNilSliceAsNull(false),
    )
}

func UnmarshalReply(data []byte, out *Reply) error {
    // 解码仍保留旧语义；调用者必须处理错误并校验业务字段。
    return jsonv2.Unmarshal(data, out, jsonv1.DefaultOptionsV1())
}

后传入的选项覆盖前面的同项设置。按这里的规则，空 Reply 编码时 items 为 []，enabled 仍被旧版 omitempty 语义省略；这是文档推导，不是运行回执。如果去掉 DefaultOptionsV1，不能假设只改变了数组：字段省略、输入匹配等默认规则也一起变了。

兼容选项解决行为迁移，不应永久掩盖协议缺陷。决定收紧重复名称或无效文本时，应单独确认哪些生产者需要修正；不要遇到错误就全局放宽。完整选项列表见 https://pkg.go.dev/encoding/json，逐项迁移说明见 https://go.dev/doc/jsonv2-migration。

权限字段和审计日志单独设边界

对用户标识、角色、租户或授权范围，编解码错误必须中止业务处理；成功后仍要检查必填项、值域和权限归属。不要在严格解码失败后自动改用宽松解析器继续执行同一次权限请求，否则前后服务可能对同一报文形成不同解释。涉及这些字段的大小写兼容，应显式写入协议，而不是依赖偶然匹配。

迁移日志记录接口标识、工具链版本、协议选项版本、错误类别与请求关联号即可。不要记录完整令牌、密码或用户原始报文。以错误类别聚合，避免依赖错误字符串逐字相等；工具链升级就可能改变错误文本。差异样本先脱敏，限制读取权限和保留时间，再供协议负责人定位。

对消费者做分组：外部公开 API 看历史契约，内部封闭请求看安全校验，消息队列还要看旧事件能否重放。未知字段策略、空值策略和字节确定性应分别管理，不能用一个“全 v1”或“全 v2”的布尔开关替代全部协议决策。

图示强调配置归属和审计关系，不代表一次实际发布已经通过检查。

发布前按消费者契约决定放行

读者可准备脱敏的代表样本，分别比较错误类别、业务对象、输出字段及必要时的原始字节。样本要包含正常值、null、空集合、false、0、字段缺失、大小写差异、重复名称、无效文本，以及实现自定义 JSON 方法的类型。字节差异不一定是业务不兼容，业务相同也不保证字节签名兼容，需由对应契约决定。

放行条件至少写清：哪些差异是批准的变化、谁是消费者负责人、哪项指标异常需要回退、回退对应哪个构建产物和语义配置。先按低风险接口小范围启用；若请求有写库、发消息等副作用，差异观察不能重复执行业务动作。观察解析差异与重复写入业务是两件不同的事。

回退优先恢复已知的旧适配层或旧构建。Go 1.27 的 nojsonv2 构建选项是暂时的实现退出机制，不是修改所有消费者契约的万能开关，也不保证未来版本仍提供。升级工具链时记录它的支持范围；不要把运行时切换选项与构建时开关混淆。

最终决策很简单：没有消费者依赖分析，就先保留旧语义；有清晰契约且差异被接受，再逐项启用 v2。迁移的交付物应该是一份可解释的协议变化清单，而不只是 import 修改记录。v2 API 的具体默认行为以 https://pkg.go.dev/encoding/json/v2 为准。