作者：迈克尔·普拉特、乔·扎伊、丹尼尔·马蒂、约翰·布兰德霍斯特-萨茨科恩、罗杰·佩佩、克里斯·海恩斯、达米恩·尼尔 | 发布日期：2026 年 11 月 4 日
背景与演进
JavaScript 对象标记 (JSON) 作为互联网上最流行的数据交换格式，在 Go 语言生态中占据核心地位。早在 Go 1.0 发布之前，标准库便已提供 JSON 支持。过去十五年间，随着用户需求的变化，encoding/json 包不断迭代。
去年，Go 团队推出了旨在解决长期痛点的新实验性 API。经过持续的反馈收集与改进，新的 encoding/json/v2 和 encoding/json/jsontext 包现已稳定，并将在 Go 1.27 版本中正式可用。本文详细解析了旧版 API 存在的缺陷，以及新版架构如何通过分层设计实现更精准的控制与性能提升。
encoding/json (v1) 的主要局限
尽管 v1 版本凭借灵活的默认表示方式和自定义能力被广泛采用，但在多年使用中暴露出若干行为、API 设计及性能层面的问题。
行为缺陷
- UTF-8 校验缺失：v1 解码器接受无效的 UTF-8 序列，而 RFC 8259 标准要求必须为有效 UTF-8。这种宽松处理可能导致无声的数据损坏及下游错误。v2 将默认报告此类错误。
- 重复键名处理：RFC 8259 未规定如何处理 JSON 对象中的重复成员名称。v1 允许重复名称，这曾导致安全漏洞（如 CVE-2017-12635）。出于安全考虑，v2 将默认拒绝包含重复名称的对象。
- Nil 值编码不一致：v1 将 nil 切片或 map 编码为 JSON
null，但这与其他许多 JSON 实现不兼容，后者期望空数组或空对象。调查显示，多数用户偏好将 nil 切片/map 默认为空结构，v2 采纳了这一变更。 - 大小写不敏感匹配：v1 在反序列化时进行大小写不敏感的字段匹配，这不仅令人困惑，还可能引发安全隐患并限制性能。v2 改为大小写敏感匹配。
- 方法调用不一致：由于实现细节，指针接收器上的
MarshalJSON方法在 v1 中被不一致地调用。虽被视为 Bug，但因依赖过多无法直接修复。
API 设计缺陷
- 流式读取困难：从
io.Reader正确解码较为棘手，常见的json.NewDecoder(r).Decode(v)用法无法拒绝输入结束后的多余垃圾数据。 - 选项配置受限：编码器/解码器的选项无法应用于顶层的
Marshal/Unmarshal函数。此外，实现Marshaler/Unmarshaler接口的类型无法访问这些选项，导致如DisallowUnknownFields等设置在自定义方法调用链中失效。 - 输出灵活性不足：部分函数强制写入
bytes.Buffer，而非更通用的[]byte或io.Writer。
性能瓶颈
- 接口开销：
MarshalJSON要求返回分配的[]byte，且需验证并重格式化 JSON。UnmarshalJSON要求传入完整 JSON 值，迫使引擎先解析边界再二次解析内容。 - 缺乏真正流式支持：即使基于 I/O 流，v1 也会在内存中缓冲整个 JSON 值。
Decoder.Token分配繁重，且无对应的 Token 写入 API。 - 递归性能退化：若自定义方法内部递归调用 Marshal/Unmarshal，性能呈二次方下降。
v2 架构：语法与语义分离
鉴于 Go 1 兼容性承诺限制了直接修改现有行为的可能性，团队引入了独立的命名空间：encoding/json/v2（简称 v2）与 encoding/json/jsontext。
新架构将 JSON 处理拆分为两个层级：
- 语法层 (
jsontext)：仅处理 JSON 文本结构，不涉及 Go 反射，负责“编码”与“解码”。 - 语义层 (
json/v2)：定义 JSON 值与 Go 值的映射关系，负责“序列化”与“反序列化”。
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 // 对应 v1 的 RawMessage
func (Value) Kind() Kind
type Token struct { ... } // 无分配设计
func (Token) Kind() Kind
为解决性能问题，v2 引入了 MarshalJSONTo 和 UnmarshalJSONFrom 接口。允许类型直接通过 jsontext.Encoder 或 Decoder 进行纯流式处理，消除了对返回值验证和边界确定的额外开销。
encoding/json/v2 核心特性
v2 的高级 API 保持了与 v1 相似的签名，但增强了灵活性和可配置性：
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 函数均接受
Options，解决了 v1 中选项无法全局传递的问题。 - 直接 I/O 操作：
MarshalWrite和UnmarshalRead直接操作 Writer/Reader，避免中间缓冲区创建。 - 自定义调度：除了类型自身实现的接口外，调用者可通过
WithMarshalers和WithUnmarshalers注入特定类型的处理逻辑，优先级高于类型默认方法。例如，ProtoJSON 示例展示了如何统一处理所有proto.Message类型。
行为差异与迁移策略
v2 在保持熟悉感的同时修正了 v1 的行为缺陷：
- 严格校验 UTF-8。
- 拒绝重复键名。
- Nil 切片/Map 编码为空数组/对象。
- 字段匹配大小写敏感。
- 重新定义
omitempty：当字段值为 null, "", [], {} 时省略。 time.Duration无默认表示，需显式配置。
值得注意的是，大部分行为差异可通过 Struct Tag 或调用选项回退至 v1 语义，便于渐进式迁移。
性能表现
基准测试显示：
- Marshal：v2 性能与 v1 大致持平，部分场景略快，部分略慢。
- Unmarshal：v2 显著优于 v1，最高可达 10 倍提升。
为了获得最佳性能，建议现有实现迁移至 MarshalerTo 和 UnmarshalerFrom 接口以利用流式处理。例如，Kubernetes 服务中将 OpenAPI 规范的递归解析从 UnmarshalJSON 切换至 UnmarshalJSONFrom 后，性能提升了数个数量级。Go 团队计划在 Go 1.28 中进一步优化 v2 的实现细节。
兼容性与共存
v1 和 v2 均受 Go 1 兼容性承诺保护，应用无需强制迁移。更重要的是，两者实现了双向兼容：
- v2 可以调用 v1 的
MarshalJSON方法。 - v1 可以在底层支持 v2 的
MarshalJSONTo等新接口。
这一机制是通过将 v1 实现为 v2 的一组特定兼容选项来达成的。因此，向后兼容的新增功能（如新方法、新标签）能自动惠及 v1 用户，促进了生态系统的平滑过渡。
