Go 推出全新 JSON API
Michael Pratt, Joe Tsai, Daniel Martí, Johan Brandhorst-Satzkorn, Roger Peppe, Chris Hines, 和 Damien Neil
2026年11月4日
简介
JavaScript Object Notation (JSON) 是一种简单的数据交换格式,也是互联网上使用最流行的数据格式,Go 程序对其有着广泛的读写支持。 Go 在 1.0 版本之前很久就在标准库中包含了 JSON 支持。 我们早在 15 年前就写过关于Go 中 JSON 支持的文章!
随着时间推移,包会随着用户需求不断演进,encoding/json 也不例外。
去年,我们介绍过一个新的 JSON 实验性 API,旨在带来期待已久的改进和修复。
经过额外的反馈和打磨,新的 encoding/json/v2 和 encoding/json/jsontext 包已经稳定并正式发布,可在 Go 1.27 中使用!
本文是介绍该实验的文章的更新版,内容涵盖了 encoding/json 存在的问题以及新包的简介。
encoding/json 的问题
总体而言,encoding/json 表现稳健。
将任意 Go 类型编组和解组为 JSON,并提供默认表示,同时允许自定义表示,这一设计被证明极具灵活性。
然而,自其推出以来的多年里,
众多用户指出了它存在的许多不足。
行为缺陷
encoding/json 存在各种行为上的缺陷:
-
JSON 语法处理不精确:多年来,为了实现程序间的正确通信,JSON 的标准化程度不断提高。 通常,解码器在拒绝歧义输入方面变得更加严格, 以降低两种实现对特定 JSON 值产生不同(成功)解释的可能性。
-
encoding/json目前接受无效的 UTF-8, 而最新的互联网标准(RFC 8259)要求有效的 UTF-8。 默认行为应当在存在无效 UTF-8 时报告错误, 而不是引入静默的数据损坏, 这可能引发下游问题。 -
encoding/json案例),此前也曾发生过(如 CVE-2017-12635)。默认行为应当从安全角度出发,拒绝重复名称。
-
-
slice 和 map 的空值问题:JSON 常用于与其他程序通信,而这些程序使用的 JSON 实现往往不允许把
null反序列化为本应是 JSON 数组或对象的数据类型。由于encoding/json会把 nil 的 slice 或 map 序列化为 JSONnull,这可能导致其他实现在反序列化时出错。一项调查显示,大多数 Go 用户希望默认把 nil 的 slice 和 map 序列化为空的 JSON 数组或对象。 -
不区分大小写的反序列化:反序列化时,JSON 对象的成员名会通过不区分大小写的匹配来对应到 Go 结构体字段。这个默认行为既令人意外,也是潜在的安全漏洞和性能瓶颈。
-
方法调用不一致:由于实现细节的原因,以指针接收者声明的
MarshalJSON方法会被encoding/json不一致地调用。虽然这被视为一个 bug,但由于太多应用依赖现有行为,无法修复。
API 的不足
encoding/json 的 API 用起来容易踩坑,也存在诸多限制:
-
从
io.Reader正确地反序列化很困难。用户通常写json.NewDecoder(r).Decode(v),但它无法拒绝输入末尾的多余内容。 -
Encoder和Decoder类型可以设置选项,但Marshal和Unmarshal函数无法使用这些选项。 同理,实现了Marshaler和Unmarshaler接口的类型也无法利用这些选项,而且没有机制将选项传递到调用堆栈深处。 例如,当调用自定义的UnmarshalJSON方法时,Decoder.DisallowUnknownFields选项就会失效。 -
Compact、Indent和HTMLEscape函数写入的是bytes.Buffer, 而不是更灵活的[]byte或io.Writer。 这限制了这些函数的适用性。
性能局限
抛开内部实现细节不谈, 公共 API 本身就承诺了某些性能局限:
-
MarshalJSON:
MarshalJSON接口方法强制实现方为返回的[]byte分配内存。 此外,语义要求encoding/json必须验证结果是否为有效的 JSON, 并重新格式化以匹配指定的缩进。 -
UnmarshalJSON:
UnmarshalJSON接口方法要求提供一个完整的 JSON 值(不含尾部多余数据)。 这迫使encoding/json必须先完整解析待反序列化的 JSON 值以确定其结束位置, 然后才能调用UnmarshalJSON。随后,UnmarshalJSON方法本身又必须再次解析提供的 JSON 值。 -
缺乏流式处理:尽管
Encoder和Decoder类型在io.Writer或io.Reader上操作, 但它们会在内存中缓冲整个 JSON 值。 用于读取单个令牌的Decoder.Token方法内存分配开销大, 且没有对应的写令牌 API。
此外,如果 MarshalJSON 或 UnmarshalJSON 方法的实现
递归调用了 Marshal 或 Unmarshal 函数,
性能将呈现二次方复杂度。
尝试直接修复 encoding/json
为包引入一个不兼容的大版本是重大决定。如果可能,我们应该尽量修复现有的包。
新增功能相对容易,但要改动现有功能就很难了。可惜这些问题源于现有 API 的设计,在 Go 1 兼容性承诺下基本无法修复。
理论上我们可以用别的名字,比如 MarshalV2 或 UnmarshalV2,但这无异于在同一个包里另建一套平行命名空间。于是就有了 encoding/json/v2(下文简称 v2),这样我们可以在独立于 encoding/json(下文简称 v1)的 v2 命名空间里做这些改动。
基于 encoding/json/jsontext 构建
在讨论 v2 API 之前,先介绍为 Go 的 JSON 改进奠定基础的 encoding/json/jsontext 包。
Go 中的 JSON 序列化可以拆成两个核心部分:
- 语法功能:基于 JSON 语法进行处理;
- 语义功能:定义 JSON 值与 Go 值之间的映射关系。
上图展示了这种划分。紫色块代表类型,蓝色块代表函数或方法,箭头方向大致表示数据流向。图中下半部分由 jsontext 包实现,只关心语法;上半部分由 json/v2 包实现,负责为下半部分处理的语法数据赋予语义。
jsontext 的基础 API 如下:
package jsontext
type Encoder struct { ... }
func NewEncoder(io.Writer, ...Options) *Encoder
func (*Encoder) WriteValue(Value) error
func (*Encoder) WriteToken(Token) error
type Decoder struct { ... }
func NewDecoder(io.Reader, ...Options) *Decoder
func (*Decoder) ReadValue() (Value, error)
func (*Decoder) ReadToken() (Token, error)
type Kind byte
type Value []byte
func (Value) Kind() Kind
type Token struct { ... }
func (Token) Kind() Kind
jsontext 包提供在语法层面处理 JSON 的功能,其名称源自 RFC 8259 第 2 节,其中定义 JSON 数据的语法确实被称为 JSON-text。由于仅在语法层面交互,它不依赖 Go 的反射机制。
Encoder 和 Decoder 支持编码和解码 JSON 值与标记。其构造函数 接受可变参数选项,用以控制具体的编码和解码行为。不同于 v1 中声明的 Encoder 和 Decoder 类型,jsontext 中的新类型避免了混淆语法与语义的区别,并采用真正的流式方式运作。
JSON 值是一个完整的数据单元,在 Go 中表示为 命名的 []byte。它与 v1 中的 RawMessage 完全一致,后者现在是 jsontext.Value 的类型别名。一个 JSON 值在语法上由一个或多个 JSON 标记组成。JSON 标记在 Go 中表示为 不透明的 Token 类型,并配有构造器访问方法。它类似于 v1 中的 Token,但设计上无需分配内存即可表示任意 JSON 标记。
要彻底解决 MarshalJSON 和 UnmarshalJSON 接口方法的性能问题,我们需要一种高效的方式,以流式 token 和值序列的形式来编解码 JSON。为此,v2 引入了基于 Encoder 或 Decoder 的 MarshalJSONTo 和 UnmarshalJSONFrom 接口方法,让方法的实现能够以纯流式方式处理 JSON。这样,json 包既不必再负责校验或格式化 MarshalJSON 返回的 JSON 值,也不必确定传给 UnmarshalJSON 的 JSON 值的边界。这些职责都交由 Encoder 和 Decoder 承担。
介绍 encoding/json/v2
在 jsontext 包的基础上,我们推出了 encoding/json/v2 包。它的目标是修复 v1 中的种种问题,同时让 v1 的老用户用起来依然熟悉。我们的目标是:把 v1 的代码直接迁移到 v2 后,大部分行为应当保持一致。
本文主要介绍 v2 的高层 API。如果想了解具体用法,建议阅读 v2 包中的示例、"Working with JSON" 教程,或 Anton Zhiyanov 的相关博客文章。
v2 的基础 API 如下:
package json
func Marshal(in any, opts ...Options) (out []byte, err error)
func MarshalWrite(out io.Writer, in any, opts ...Options) error
func MarshalEncode(out *jsontext.Encoder, in any, opts ...Options) error
func Unmarshal(in []byte, out any, opts ...Options) error
func UnmarshalRead(in io.Reader, out any, opts ...Options) error
func UnmarshalDecode(in *jsontext.Decoder, out any, opts ...Options) error
Marshal 和 Unmarshal 函数的签名与 v1 类似,但支持传入选项以配置其行为。MarshalWrite 和 UnmarshalRead 函数直接操作 io.Writer 或 io.Reader,无需为了读写这类类型而临时构造 Encoder 或 Decoder。MarshalEncode 和 UnmarshalDecode 函数作用于 jsontext.Encoder 和 jsontext.Decoder,实际上它们是前述函数的底层实现。与 v1 不同,选项在 v2 的编解码函数中是一等公民参数,极大地提升了 v2 的灵活性和可配置性。v2 中还提供了若干可用选项,本文不予赘述。
指定类型的自定义
与 v1 类似,v2 允许类型通过实现特定接口来定义自己的 JSON 表示方式。
type Marshaler interface {
MarshalJSON() ([]byte, error)
}
type MarshalerTo interface {
MarshalJSONTo(*jsontext.Encoder) error
}
type Unmarshaler interface {
UnmarshalJSON([]byte) error
}
type UnmarshalerFrom interface {
UnmarshalJSONFrom(*jsontext.Decoder) error
}
Marshaler 和 Unmarshaler 接口与 v1 中的完全一致。新增的 MarshalerTo 和 UnmarshalerFrom 接口则允许类型通过 jsontext.Encoder 或 jsontext.Decoder 将自身表示为 JSON。这样还能把配置选项沿调用链向下传递,因为可以通过 Encoder 或 Decoder 上的 Options 访问方法获取这些选项。
关于如何实现一个能保持 JSON 对象成员顺序的自定义类型,可以参考 OrderedObject 示例。
调用方自定义
在 v2 中,Marshal 和 Unmarshal 的调用方可以为任意类型指定自定义的 JSON 表示形式,而且调用方提供的函数优先级高于类型自身定义的方法或默认表示形式。
func WithMarshalers(*Marshalers) Options
type Marshalers struct { ... }
func MarshalFunc[T any](fn func(T) ([]byte, error)) *Marshalers
func MarshalToFunc[T any](fn func(*jsontext.Encoder, T) error) *Marshalers
func WithUnmarshalers(*Unmarshalers) Options
type Unmarshalers struct { ... }
func UnmarshalFunc[T any](fn func([]byte, T) error) *Unmarshalers
func UnmarshalFromFunc[T any](fn func(*jsontext.Decoder, T) error) *Unmarshalers
MarshalFunc 和 MarshalToFunc 用于构造自定义 marshaler,通过 WithMarshalers 传给 Marshal 调用,即可覆盖特定类型的序列化行为。类似地,UnmarshalFunc 和 UnmarshalFromFunc 为 Unmarshal 提供了相应的自定义能力。
ProtoJSON 示例展示了该特性如何让所有 proto.Message 类型的序列化由 protojson 包处理。
行为差异
v2 旨在在大多数情况下保持与 v1 一致的行为,但为了解决 v1 中的问题,其在某些方面(详见此处)做出了改变,最显著的是:
-
遇到无效 UTF-8 时,
v2会报告错误。 -
当 JSON 对象包含重复的名称时,
v2会报告错误。 -
v2将 nil 的 Go 切片或 Go 映射分别序列化为空的 JSON 数组或 JSON 对象。 -
v2在将 JSON 对象反序列化为 Go 结构体时,采用区分大小写的方式匹配 JSON 成员名与 Go 字段名。 -
v2重新定义了omitempty标签选项:如果字段编码后为“空”的 JSON 值(即null、""、[]或{}),则省略该字段。 -
尝试序列化
time.Duration时,v2会报告错误,因为该类型目前没有默认表示形式,但提供了选项供调用方自行决定。
对于大多数行为变更,都提供了结构体标签选项或调用方指定选项,可用于配置行为以遵循 v1 或 v2 语义,甚至实现其他由调用方决定的行为。
更多信息请参见“迁移至 v2”。
性能优化
v2 的 Marshal 性能与 v1 大致持平,有时略快,有时略慢。v2 的 Unmarshal 性能则显著快于 v1,基准测试显示性能提升最高可达 10 倍。
要获得更高的性能提升,现有的 Marshaler 和 Unmarshaler 实现应迁移为同时实现 MarshalerTo 和 UnmarshalerFrom,这样才能以纯流式方式处理 JSON 并从中受益。例如,在 UnmarshalJSON 方法中对 OpenAPI 规范进行递归解析,曾严重拖慢 Kubernetes 某个服务的性能(参见 kubernetes/kube-openapi#315);而改用 UnmarshalJSONFrom 后,性能提升了几个数量级。
更多基准测试细节请参考 go-json-experiment/jsonbench 仓库。
除了结构性改进,我们还在持续投入性能优化,解决 一些 v2 比 v1 慢的 情况。Go 1.28 中还会有进一步的改进。
兼容性
Go 1 兼容性承诺是 Go 项目的核心保障,让开发者构建的应用能够经受时间考验,在未来版本的 Go 中继续正常工作。
原有的 encoding/json 和新的 encoding/json/v2 包自然都受 Go 1 兼容性承诺约束。使用 v1 的应用会被无限期支持,永远不需要迁移到 v2。
不过在设计 v2 包时,我们想做的不仅仅是继续支持 v1。我们希望确保 v1 和 v2 彼此兼容,让使用不同版本的包能够协同工作。这样可以实现生态系统的平稳迁移,而不是因为依赖方的选择而迫使用户只能用某个版本。
例如,假设你的包使用 v2 来序列化一个结构体,而该结构体中包含一个在另一个包中定义的类型字段。那个包可能使用原始的 v1 MarshalJSON 方法定义其序列化行为。没有问题,v2 支持 MarshalJSON 方法,因此序列化会按预期继续正常工作。
反之亦然,假设你的包使用 v1 来序列化同一个结构体。另一个包可能使用 v2 的 MarshalJSONTo 方法以获得更好的性能。这里也没有问题,因为 v1 实现在底层支持 v2 的 MarshalJSONTo 方法。
我们这样设计新包,使得底层 v1 是建立在 v2 基础之上的。如前所述,v2 支持多种 Options。每种行为差异都由其中一个选项控制。因此,v1 可以通过传入完整的 v1 兼容性选项集,用 v2 来实现。
通过这种方式,向后兼容的补充(例如新方法(MarshalJSONTo)或新的结构体标签(embed))会自动得到支持,让现有的 v1 用户也能从中受益。
迁移
用 v2 选项实现 v1 还带来额外好处,允许调用点逐步迁移。
encoding/json 的文档详细说明了 v1 和 v2 之间完整的行为差异,以及由哪些选项控制这些行为。
许多应用可以直接迁移到 v2,而没有任何可见的行为变化;但依赖 v1 行为的应用可以使用选项,仅改变其所依赖的那些行为。
例如,我们可以选择所有 v2 行为,但允许重复名称:
json.Marshal(..., json.DefaultOptionsV2(), jsontext.AllowDuplicateName(true))
也可以选择所有 v1 行为,但不允许重复名称:
json.Marshal(..., jsonv1.DefaultOptionsV1(), jsontext.AllowDuplicateName(false))
更多细节请参阅 encoding/json/v2 迁移指南,其中覆盖了从 v1 迁移到 v2 的多种场景。
更多信息
关于新 JSON 包的更多参考资料,请参阅:
- “Working with JSON” 教程
encoding/json/v2和encoding/json/jsontext的包文档encoding/json包中与v2的对比文档- 以及
encoding/json/v2迁移指南
姗姗来迟
为新版 encoding/json 做规划花了数年时间。2020 年底,由于现有包的问题难以修复,encoding/json 的维护者之一 Daniel Martí 起草了一份文档,阐述了他对假想中 v2 包应有的样子的看法。另一方面,Joe Tsai 在完成 Go API for Protocol Buffers 的工作后感到失望:protojson 包不得不使用自定义的 JSON 实现,因为 encoding/json 既无法满足 Protocol Buffer 规范所要求的更严格的 JSON 标准,也无法以流式方式高效地序列化 JSON。
相信 JSON 拥有更光明的未来,且这一目标既有益又可达成,Daniel 和 Joe 联手为 v2 进行头脑风暴,并开始构建原型(初始代码源自 Go protobuf 模块中精炼后的 JSON 序列化逻辑)。随着时间推移,Roger Peppe、Chris Hines、Johan Brandhorst-Satzkorn、Damien Neil、Austin Clements 和 Michael Pratt 等人也加入了这一工作,提供设计审查、代码审查和回归测试支持。许多早期讨论可通过我们的会议录像和会议记录公开查阅。后期的讨论则收录在 encoding/json/v2 工作组会议记录中。
这项工作自始至终保持公开,我们不断吸纳更广泛的 Go 社区参与。途径包括:GopherCon 演讲、2023 年底发布的讨论帖、2025 年初的正式提案,以及最终在 Go 1.25 中将 encoding/json/v2 作为 Go 实验特性引入,以便所有 Go 用户进行大规模测试。
v2 项目历时约 6 年才走到今天,期间吸纳了众多贡献者的反馈,并在生产环境使用中积累了宝贵的实践经验。
值得一提的是,该项目主要由未在 Google 任职的人士开发和推广,这证明了 Go 项目是一项协作事业,拥有一个致力于改善 Go 生态系统的活跃全球社区。
感谢所有做出贡献的人!
上一篇: 对 eMudhra 密钥泄露事件的回应
博客索引