Go 官方博客更新了 JSON 序列化的进展:经过额外一年的反馈与打磨,encoding/json/v2 与 encoding/json/jsontext 两个包在 Go 1.27 进入稳定状态,正式一般可用(GA)。距离这个提案首次公开讨论已经过去六年,距离它在 Go 1.25 以实验包形式落地过去两个版本周期。对写 Go 的人来说,这是标准库里少有的大动作:一个每天被无数服务调用的包,换了底层实现和一套新 API,同时承诺旧代码一行不改也能继续跑。
v1 欠下的三类账
官方文章把 encoding/json(下称 v1)的问题分成三层。
行为层最要命的几条:v1 接受无效 UTF-8 输入,而 RFC 8259 要求 UTF-8 必须有效,默认放行的结果是静默数据损坏;v1 接受带重复成员名的 JSON 对象,任选一个值解出来,这类歧义输入在安全场景被真实利用过(CVE-2017-12635);nil slice 会被序列化成 null,对接那些不允许把 null 解成数组类型的实现时直接报错,官方调查显示多数 Go 用户希望默认输出空数组;反序列化时成员名与结构体字段的匹配是大小写不敏感的,官方将其列为意外行为、潜在安全漏洞和性能负担三重问题。还有一条修不了的:MarshalJSON 方法在指针接收者上的调用行为不一致,但太多应用依赖现状,动不得。
| 问题 | v1 行为 | 后果 |
|---|---|---|
| 无效 UTF-8 | 默默接受 | 静默数据损坏,下游出错 |
| 重复成员名 | 任选一个值 | 歧义输入可被攻击者利用 |
| nil slice/map | 序列化为 null | 严格实现的对端解析失败 |
| 字段名匹配 | 大小写不敏感 | 意外行为 + 安全 + 性能三重负担 |
API 层的缺陷集中在「选项传不下去」。DisallowUnknownFields 这类选项只能设在 Decoder 上,一旦类型自己实现了 UnmarshalJSON,选项在自定义方法里就失效了,没有任何机制把选项沿调用栈下传。Compact、Indent、HTMLEscape 三个函数只肯写 bytes.Buffer。用 json.NewDecoder(r).Decode(v) 读流的用户还经常踩一个坑:它不拒绝输入末尾的垃圾数据。
性能层的限制则是 API 语义锁死的。MarshalJSON 接口方法必须返回 []byte,实现方被迫分配内存,标准库还得校验返回值是不是合法 JSON 并按缩进要求重新排版;UnmarshalJSON 要求拿到完整的 JSON 值,标准库必须先完整解析一遍确定值的边界,方法内部再自己解析一遍,同一个值被解析两次。Encoder/Decoder 虽然挂在 io.Writer/io.Reader 上,实际却把整个 JSON 值缓冲在内存里,Decoder.Token 分配很重,而且没有写 token 的对应 API。官方还点了一个组合拳:如果 MarshalJSON 实现里递归调用 Marshal,性能会退化成二次方复杂度。
这些问题没有一条能在 Go 1 兼容承诺下原地修复。这就是 v2 存在的理由:换个命名空间,把该改的都改掉。
先立地基:jsontext 把语法和语义拆开
v2 的设计起点是一次概念切分:encode/decode 只管语法(JSON 文本合不合法),marshal/unmarshal 只管语义(JSON 值与 Go 值怎么对应)。新包 encoding/json/jsontext 承担前者,名字来自 RFC 8259 第 2 节对 JSON 语法的正式称呼「JSON-text」。
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几个关键设计:Value 是一个具名 []byte,v1 的 RawMessage 现在就是它的类型别名;Token 是不透明类型,代表任意 JSON token 且不产生分配;Encoder/Decoder 的构造函数接受变长 options,行为可以逐次定制。最重要的变化藏在「真流式」三个字里:jsontext 的读写不再缓冲完整值,token 一条一条过。

针对 v1 那组性能死结,v2 给出了新接口:MarshalJSONTo(*jsontext.Encoder) 和 UnmarshalJSONFrom(*jsontext.Decoder)。实现方直接在流上读写,标准库不再需要校验、重排版返回值,也不再需要预解析确定边界。递归实现从二次方复杂度回到线性。
v2 的入口:六个函数加一等公民 options
encoding/json/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每对操作按「内存 / 流 / 编码器」三个层级各给一个入口,MarshalEncode 和 UnmarshalDecode 是其余四个的底层实现。options 从 v1 的「只能设在 Encoder/Decoder 上」变成每个函数的显式参数,这是 v1 时代选项传不下去问题的正面解法。
定制点分两级。类型级:类型可以实现 MarshalerTo/UnmarshalerFrom,options 通过 Encoder/Decoder 的访问器取到,顺着调用栈一路传下去。调用方级:WithMarshalers + MarshalFunc[T] 允许调用者替任意类型指定序列化行为,且优先级高于类型自己的方法。官方给的例子是 ProtoJSON:注册一个针对 proto.Message 的 marshaler,所有 protobuf 类型的序列化就都交给 protojson 处理,业务结构体与 proto 结构体混在一个 struct 里也能正确编码。
升级清单:六个行为差异
直接迁移到 v2 的代码大部分行为不变,官方明确列出的差异有六条:
| # | v1 | v2 |
|---|---|---|
| 1 | 无效 UTF-8 默默接受 | 报错 |
| 2 | 重复成员名任选其一 | 报错 |
| 3 | nil slice/map → null | 序列化为 [] / {} |
| 4 | 字段名大小写不敏感匹配 | 大小写敏感匹配 |
| 5 | omitempty 按 Go 零值省略 | 编码结果为空 JSON 值(null、""、[]、{})才省略 |
| 6 | time.Duration 有默认表示 | 序列化报错,由调用方通过 options 决定 |
第 5 条值得展开一句:v1 的 omitempty 判断的是 Go 值是否为零值,0 和 false 也会被省略;v2 改成判断编码后的 JSON 值是否为空,数字 0 会正常输出。第 6 条则是把「Duration 该表示成字符串还是纳秒数」这个历史遗留的决定权交还调用方。
每一条差异都有对应的 option 可以切回 v1 语义,这也是迁移策略的基础。
性能账本
官方给出的数字分两半:Marshal 与 v1 大致持平,互有快慢;Unmarshal 显著更快,基准测试最高 10 倍提升。想拿到更大收益,路径是把自定义类型从 MarshalJSON/UnmarshalJSON 迁移到 MarshalJSONTo/UnmarshalJSONFrom,吃上纯流式处理。官方引用的实例来自 Kubernetes:某项服务在 UnmarshalJSON 里递归解析 OpenAPI 规范,性能被显著拖慢(kubernetes/kube-openapi#315),换成 UnmarshalJSONFrom 后提升以数量级计。v2 实现仍慢于 v1 的场景,官方表示 Go 1.28 会继续投入优化。
兼容策略:v1 由 v2 实现
这次重构里工程上最讲究的一步是兼容设计。v1 包受 Go 1 兼容承诺保护,会被无限期支持,应用可以永不迁移。更进一步,官方让 v1 在底层直接用 v2 实现:把全部 v1 兼容行为打包成一组 options 传给 v2,v1 的 API 就成了 v2 的一层薄壳。
两个方向都打通了:你的包用 v2 序列化一个结构体,字段类型定义在另一个用 v1 MarshalJSON 的包里,照常工作;反过来,v1 的 Marshal 遇到实现了 v2 MarshalJSONTo 的类型,同样正常。依赖不同版本 JSON 包的库可以自由组合,生态迁移不需要齐步走。
逐行为微调也留了口子。想要全部 v2 行为但放行重复成员名:
json.Marshal(..., json.DefaultOptionsV2(), jsontext.AllowDuplicateName(true))想要全部 v1 行为但拒绝重复成员名:
json.Marshal(..., jsonv1.DefaultOptionsV1(), jsontext.AllowDuplicateName(false))完整的差异对照和迁移场景收录在官方 Migration Guide 里。
六年时间线
这件事的起点在 2020 年末。Daniel Martí(encoding/json 维护者之一)受困于现有包修不动的问题,起草了 v2 的最初构想;Joe Tsai 在做完 Go 的 Protocol Buffers API 后,发现 protojson 被迫自带一套私有 JSON 实现,因为 encoding/json 既达不到 protobuf 规范要求的严格标准,也做不了流式序列化。两人合作的原型代码,就是从 Go protobuf 模块的 JSON 序列化逻辑打磨出来的。
后续加入的贡献者包括 Roger Peppe、Chris Hines、Johan Brandhorst-Satzkorn、Damien Neil、Austin Clements 和 Michael Pratt,分别负责设计评审、代码评审和回归测试。项目全程公开:2023 年末的 GopherCon 演讲和讨论,2025 年初的正式提案,Go 1.25 的实验落地,到 Go 1.27 一般可用,整个周期约六年。官方在文末特别说明,这项工作主要由非 Google 雇员的贡献者开发和推动。
来源: