A new Go API for JSON
TL;DR · AI 摘要
Go 1.27 引入 encoding/json/v2 和 encoding/json/jsontext 包,解决 JSON 处理中的 UTF-8、nil 值和大小写问题。
核心要点
- Go 1.27 新增 encoding/json/v2 包,强制校验 UTF-8 和拒绝重复字段。
- 75% Go 用户希望 nil 切片/映射默认序列化为空数组/对象。
- 新 API 修复了 CVE-2017-12635 安全漏洞风险。
结构提纲
按章节快速跳转。
- §引言
介绍 Go 1.27 新增 JSON 处理包的背景与目标。
分析 UTF-8 处理、nil 值泄漏和大小写不敏感等缺陷。
encoding/json/v2 强制校验 UTF-8 并拒绝重复字段。
75% 用户希望 nil 切片/映射默认序列化为空结构。
- ›安全增强
修复 CVE-2017-12635 漏洞的重复字段攻击风险。
- ›迁移建议
推荐新项目使用 encoding/json/v2 替代旧包。
思维导图
用一张图看清主题之间的关系。
查看大纲文本(无障碍 / 无 JS 友好)
- Go 1.27 JSON API 改进
- 问题修复
- UTF-8 校验
- 拒绝重复字段
- nil 值处理
- 新特性
- encoding/json/v2
- encoding/json/jsontext
金句 / Highlights
值得收藏与分享的关键句。
encoding/json 当前接受无效 UTF-8,违反 RFC 8259 标准。
75% Go 用户希望 nil 切片/映射默认序列化为空 JSON 结构。
重复字段可能导致安全漏洞(如 CVE-2017-12635)。
用于 JSON 的新 Go API - Go 编程语言
Go 博客
用于 JSON 的新 Go API
Michael Pratt, Joe Tsai, Daniel Martí, Johan Brandhorst-Satzkorn, Roger Peppe, Chris Hines, 和 Damien Neil 2026年11月4日
引言
JavaScript 对象表示法(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 当前接受包含重复成员名的对象。RFC 8259 未规定如何处理重复名称,因此实现可以选择任意值、合并值、丢弃值或报告错误。重复名称的存在会导致 JSON 值缺乏普遍共识的含义。这在安全应用中可能被攻击者利用,此前已发生过类似事件(如 CVE-2017-12635)。默认行为应优先考虑安全性,拒绝重复名称。
- 泄漏切片和映射的 nil 状态:JSON 常用于与使用不允许将 null 反序列化为预期 JSON 数组或对象的数据类型的程序通信。由于 encoding/json 将 nil 切片或映射序列化为 JSON null,这可能导致其他实现反序列化时出错。调查显示大多数 Go 用户希望默认将 nil 切片和映射序列化为空 JSON 数组或对象。
- 反序列化不区分大小写:反序列化时,JSON 对象成员名通过不区分大小写的匹配解析到 Go 结构体字段名。这是令人意外的默认行为,可能带来安全漏洞,并限制性能表现。
- 方法调用不一致:由于实现细节,声明在指针接收者上的 MarshalJSON 方法会被 encoding/json 不一致地调用。尽管这被视为一个错误,但无法修复,因为太多应用程序依赖于当前行为。
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 ),在单独的 v2 命名空间内进行这些更改,与 encoding/json (以下简称 v1 )形成对比。
基于 encoding/json/jsontext 的构建
在讨论 v2 API 之前,我们首先介绍 encoding/json/jsontext 包,该包为 Go 中 JSON 的改进奠定了基础。
Go 中的 JSON 序列化可以分解为两个主要组件:
- 与 JSON 语法处理相关的功能,
/think
- 定义 JSON 值与 Go 值之间关系的语义功能。
我们使用“encode”和“decode”来描述语法功能,使用“marshal”和“unmarshal”来描述语义功能。我们的目标是明确区分仅关注编码功能与关注序列化功能之间的差异。
该图表展示了这种分离的概览。紫色方块表示类型,蓝色方块表示函数或方法。箭头的方向大致表示数据流动方向。图表下半部分由 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() Kindjsontext 包提供在语法层面与 JSON 交互的功能,其名称来源于 RFC 8259 第 2 节,该节中 JSON 数据语法被直接称为 JSON-text。由于它仅在语法层面与 JSON 交互,因此不依赖 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 接口方法的根本性能问题,我们需要一种高效的 JSON 编码/解码方式,以流式标记和值序列进行处理。在 v2 中,我们引入了 MarshalJSONTo 和 UnmarshalJSONFrom 接口方法,它们作用于 Encoder 或 Decoder,使方法实现能够以纯粹的流式方式处理 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) errorMarshal 和 Unmarshal 函数的签名与 v1 类似,但接受选项来配置其行为。MarshalWrite 和 UnmarshalRead 函数直接操作 io.Writer 或 io.Reader,避免了为写入或读取此类类型而临时构造 Encoder 或 Decoder 的需要。MarshalEncode 和 UnmarshalDecode 函数作用于 jsontext.Encoder 和 jsontext.Decoder,实际上是前面提到函数的底层实现。与 v1 不同,选项是每个序列化和反序列化函数的一等参数,大大增强了 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 访问器方法获取选项。
参见 OrderedObject 示例,了解如何实现一个自定义类型以保持 JSON 对象成员的顺序。
调用者指定的自定义
在 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) *UnmarshalersMarshalFunc 和 MarshalToFunc 构造一个自定义的序列化器,可以通过 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 的优势。例如,在 Kubernetes 的某个服务中,UnmarshalJSON 方法对 OpenAPI 规范的递归解析显著影响了性能(参见 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 兼容性选项,就可以用 v2 实现 v1。
采用这种方法,向后兼容的新增功能(例如新方法(如 MarshalJSONTo)或新结构标签(如 embed))会自动被现有 v1 用户受益。
迁移
通过将 v1 实现为 v2 的选项,还可以实现调用站点的逐步迁移。
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 包应具备功能的想法。与此同时,在之前为 Go 的 Protocol Buffers API 做过工作的 Joe Tsai 对 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 社区参与进来,首先是 2023 年末发布的 GopherCon 演讲和讨论,然后是 2025 年初发布的正式提案,最后在 Go 1.25 中将 encoding/json/v2 作为 Go 实验功能,供所有 Go 用户进行更大规模的测试。
v2版本的开发工作历时约6年才达到这一阶段,期间吸纳了众多贡献者的反馈,并通过在生产环境中的实际应用积累了宝贵的实践经验。
需要特别指出的是,该版本主要由非Google员工的开发者推动和推广,这充分体现了Go项目作为一项协作性工程的特性,其背后有着一个充满活力的全球社区,致力于改进Go生态系统。
感谢所有贡献者!
上一篇文章:Our Response To The eMudhra Key Disclosure Incident Blog Index