Go 1.27 正式稳定 encoding/json/v2 与 jsontext
Go 1.27 将 encoding/json/v2 与 encoding/json/jsontext 标记为稳定,修复旧版 JSON API 在 UTF-8、重复键、nil 切片与 map 处理上的行为问题,并引入流式接口。
旧 API 的行为缺陷
encoding/json 从 Go 1.0 之前就存在于标准库,但长期积累了一些难以通过兼容性承诺修复的问题。它接受无效的 UTF-8,而 RFC 8259 要求 JSON 文本必须是有效 UTF-8;默认行为应报错而非让损坏的数据进入下游。它还会接受包含重复成员名的对象。RFC 8259 没有规定重复名称的处理方式,同一份 JSON 在不同实现中可能产生不同结果,这类歧义已被用于安全攻击,例如 CVE-2017-12635。默认行为改为拒绝重复名称。nil 切片和 map 被序列化为 null,但许多 JSON 实现期望数组或对象;一项调查显示多数 Go 用户希望默认输出空数组或空对象。反序列化时对象成员名与 Go 结构体字段名采用大小写不敏感匹配,这一默认行为带来意外、安全风险和性能损失。指针接收者上的 MarshalJSON 方法调用不一致,已被视为 bug,但由于大量应用依赖现有行为,无法直接修复。
设计上的限制
除行为问题外,API 本身也存在限制。从 io.Reader 正确反序列化比较困难,常见的 json.NewDecoder(r).Decode(v) 不会拒绝输入末尾的多余数据。选项只能设置在 Encoder 和 Decoder 类型上,无法用于 Marshal 和 Unmarshal 函数;实现 Marshaler 或 Unmarshaler 接口的类型也无法访问这些选项。例如 Decoder.DisallowUnknownFields 在调用自定义 UnmarshalJSON 方法时会失效。Compact、Indent 和 HTMLEscape 只能写入 bytes.Buffer,而不是更灵活的 []byte 或 io.Writer。性能方面,MarshalJSON 强制分配返回的 []byte,并要求 encoding/json 验证和重新格式化结果;UnmarshalJSON 要求提供完整 JSON 值,导致 encoding/json 必须先解析出边界,再由方法本身二次解析。流式能力也很有限,Encoder 和 Decoder 会在内存中缓冲整个 JSON 值,递归调用 Marshal 或 Unmarshal 时性能可能变成二次方。
jsontext 与 v2 的新接口
Go 1.27 将 encoding/json/v2 和 encoding/json/jsontext 标记为稳定。jsontext 包负责语法层面的编码和解码,不依赖反射,提供 Encoder、Decoder、Value 和 Token 类型。Value 是命名的 []byte,与 v1 的 RawMessage 相同,后者现在成为 jsontext.Value 的类型别名。Token 设计为无分配地表示任意 JSON token。为了解决 MarshalJSON 和 UnmarshalJSON 的性能问题,v2 新增 MarshalJSONTo 和 UnmarshalJSONFrom 接口,方法直接操作 Encoder 或 Decoder,以流式方式处理 JSON,无需 encoding/json 验证或确定边界。
v2 的 Marshal 和 Unmarshal 函数接受可选参数,并新增 MarshalWrite、UnmarshalRead、MarshalEncode、UnmarshalDecode 直接操作 io.Writer、io.Reader 或 jsontext 类型。调用方还可以通过 WithMarshalers 和 WithUnmarshalers 为任意类型指定自定义序列化逻辑,优先级高于类型自身定义的方法。
行为调整与兼容性
v2 改变了一些默认行为:遇到无效 UTF-8 或对象重复名称时报错;nil 切片和 map 序列化为空数组或空对象;反序列化改为大小写敏感匹配;omitempty 标签重新定义为字段编码为空 JSON 值(null、“”、[]、{})时省略;序列化 time.Duration 时报错,因为该类型没有默认表示,由调用方通过选项决定。多数行为差异可以通过结构体标签或调用方选项切回 v1 语义。
性能基准显示 v2 的 Marshal 性能与 v1 大致持平,Unmarshal 显著更快,最高提升 10 倍。将 Marshaler 和 Unmarshaler 迁移到新的流式接口可进一步改善性能,例如 Kubernetes 的 OpenAPI 递归解析在改用 UnmarshalJSONFrom 后性能提升数个数量级。v1 与 v2 可互操作,v1 在底层由 v2 实现,现有 v1 用户无需迁移。Go 1.28 预计还会继续优化 v2 实现中比 v1 慢的场景。