跳至主要內容

json v2 到底有多好用?

Ryan SU2025/8/23大约 8 分钟GolangGolang 教程

json v2 到底有多好用?

Go 标准库中的 encoding/json 包是我们日常开发中最常用的包之一，已在 Go 生态中服务超过十年，应用极其广泛。然而，该包也因为一些长期存在的设计问题——如部分 API 的行为不一致、灵活性不足以及在性能敏感场景下的瓶颈——而受到社区的多次讨论和批评。
值得关注的是，Go 官方团队在 v1.25.0 版本对 encoding/json 进行重大升级，推出了下一代实现：encoding/json/v2，并可通过实验性环境变量 GOEXPERIMENT=jsonv2 进行体验。

为什么需要 json/v2？

在具体实践之前，我们不妨先回顾一下 encoding/json（v1）长期存在的核心问题。Go 官方在提案 #71497 中将其总结为以下四类：

一、行为缺陷

  • 大小写敏感的字段匹配：v1 在反序列化时采用大小写不敏感的字段匹配策略，虽便于使用，但不符合 RFC 8259 中关于 JSON 对象键应区分大小写的建议，易引发非预期行为。
  • 重复键处理模糊：v1 对重复键的处理未定义（通常后值覆盖前值），且不报错，违背了 RFC 建议的“对象键应唯一”的原则。
  • 无效 UTF-8 的静默替换：v1 会将无效 UTF-8 序列替换为 Unicode 替换字符（U+FFFD），而不是报错。v2 则默认要求严格的 UTF-8 输入。
  • null 反序列化行为不一致：v1 对 null 反序列化到非零值时的处理因类型而异，v2 将其统一为“清零”。
  • 合并语义不统一：v1 在反序列化至现有结构体或 map 时，合并逻辑存在类型差异。v2 重新设计了一套更一致的合并策略。

二、功能缺失

  • 时间格式不够灵活：v1 强制时间字段使用 RFC 3339 格式，无法轻松兼容其他常见时间表示形式。
  • omitempty 机制局限：v1 的 omitempty 基于类型的零值判断，无法区分“值为零”和“字段不存在”的情形。v2 引入 omitzero，提供更精确的控制（注：v1 也已通过补丁支持该机制）。
  • 无法便捷处理未知字段：v1 会直接丢弃未知字段，缺乏内置机制捕获这些内容。
  • nil 切片与映射的序列化结果不符合预期：v1 将 nil slice 和 map 序列化为 null，而非更常见的 [] 和 {}。

三、API 设计问题

  • 缺乏对 io.Reader/Writer 的原生支持：v1 主要基于 []byte 操作，与 Go 中广泛使用的流式 IO 接口整合不够自然。
  • 配置不够细粒度：如 DisallowUnknownFields 和 UseNumber 等设置作用于整个解码器，无法基于字段或类型进行灵活控制。

四、性能瓶颈

  • 反射开销较大：v1 大量依赖反射，处理复杂或大规模 JSON 数据时性能较差。
  • 内存分配策略非最优：在序列化与反序列化过程中可能产生过多内存分配，增加 GC 压力。

json v2 的用法有何不同?

重要

行为正确性：重复键报错与大小写敏感

在 encoding/json (v1) 中，若 JSON 对象存在重复键，默认行为并不报错，而是不确定地（通常以后者覆盖前者）处理，这容易引发数据混乱。此外，其在字段匹配时采用大小写不敏感的方式，也与现代 JSON 标准（RFC 8259）中强调的“名称区分大小写”原则不符，可能导致非预期的映射结果。json/v2 对这些行为作出了重要调整，更加严格地遵循标准并提升一致性。

时间与时长处理的灵活性增强

v1 版本对时间类型（time.Time）强制使用 RFC 3339 格式，对时长（time.Duration）则默认序列化为整型纳秒。这种设定在与外部系统交互或需要良好可读性时显得不够友好。json/v2 通过引入 format 标签选项，显著提升了对时间和时长类型的格式控制能力，支持更灵活的输入输出形式。


type EventData struct {
    EventName   string        `json:"event_name"`
    Timestamp   time.Time     `json:"timestamp,format:'2006-01-02'"`          // v2: 自定义日期格式
    PreciseTime time.Time     `json:"precise_time,format:RFC3339Nano"`        // v2: RFC3339 Nano 格式
    Duration    time.Duration `json:"duration"`                               // v2 默认输出 "1h2m3s" 格式
    Timeout     time.Duration `json:"timeout,format:sec"`                     // v2: 以秒为单位的数字
    OldDuration time.Duration `json:"old_duration,format:nano"`                 // v2: 兼容v1的纳秒数字
}

omitempty 优化与 omitzero 的引入

v1 中的 omitempty 行为基于 Go 类型的零值进行判断，而 v2 则改为依据字段编码后的 JSON 值是否为空（如 ""、null、[]、{}）来决定是否省略。为进一步区分“零值”与“不存在”的情形，v2 还引入了 omitzero 标签（该特性也已向后移植至 v1.24+ 版本），为用户提供更精确的序列化控制。

type WebConfig struct {
    // 启用状态
    // v1: 当值为 false 时会被省略
    // v2: 仅当值为 false 且不编码为空值时才不会被省略
    Enabled     bool    `json:"enabled,omitempty"`
    
    // 计数
    // v1: 当值为 0 时会被省略
    // v2: 仅当值为 0 且不编码为空值时才不会被省略
    Count       int     `json:"count,omitempty"`
    
    // 名称
    // v1 和 v2 行为一致: 当值为空字符串("")时会被省略
    Name        string  `json:"name,omitempty"`
    
    // 描述信息(指针类型)
    // v1 和 v2 行为一致: 当值为 nil 时会被省略
    Description *string `json:"description,omitempty"`

    // 是否设置
    // v1 和 v2 行为一致: 使用 omitzero 标签，当值为 false 时会被省略
    IsSet  bool    `json:"is_set,omitzero"`
    
    // 端口号
    // v1 和 v2 行为一致: 使用 omitzero 标签，当值为 0 时会被省略
    Port   int     `json:"port,omitzero"`
    
    // API 密钥(指针类型)
    // v1 和 v2 行为一致: 使用 omitzero 标签，当值为 nil 时会被省略
    APIKey *string `json:"api_key,omitzero"`
}

nil 切片与映射的序列化行为调整

在 v1 中，nil 切片和映射默认被序列化为 null，这种做法常与开发者期望的输出（[] 或 {}）不符。json/v2 调整了默认行为，将它们序列化为空数组和空对象，同时也提供 format:emitnull` 标签选项，以满足向后兼容或特定场景的需求。

type TagData struct {
    // 标签列表
    // 当为 nil 切片时，根据全局配置决定序列化方式
    // （参考 FormatNilSliceAsNull 选项）
    Tags       []string          `json:"tags"`                       
    
    // 属性映射
    // 当为 nil 映射时，根据全局配置决定序列化方式
    // （参考 FormatNilMapAsNull 选项）
    Attrs      map[string]string `json:"attrs"`                      
    
    // 可能的标签列表
    // v2 版本特有：使用 format:emitnull 标签
    // 无论全局配置如何，当为 nil 切片时强制序列化为 null
    MaybeTags  []string          `json:"maybe_tags,format:emitnull"`  
    
    // 可能的属性映射
    // v2 版本特有：使用 format:emitnull 标签
    // 无论全局配置如何，当为 nil 映射时强制序列化为 null
    MaybeAttrs map[string]string `json:"maybe_attrs,format:emitnull"` 
}
// v1 结果

 {
  "tags": null,
  "attrs": null,
  "maybe_tags": null,
  "maybe_attrs": null
}

// v2 结果

 {
    "tags": [],
    "attrs": {},
    "maybe_tags": null,
    "maybe_attrs": null
}

强大的新结构体标签选项：inline 与 unknown

json/v2 引入了数个新的结构体标签选项，显著增强了对序列化与反序列化流程的控制能力。其中两个尤为实用的选项是 inline 和 unknown：

  • inline：允许将内嵌结构体字段（或普通结构体字段）“展开”到父结构体中进行编码，不再以嵌套对象形式呈现。
  • unknown：使未被结构体明确定义的 JSON 字段可以被收集到指定字段（类型可为 map 或 jsontext.Value）中，而非像 v1 那样直接丢弃，极大提升了对外部数据的兼容性。

type Address struct {
    Street string `json:"street"`
}
type Person struct {
    Name    string  `json:"name"`
    Address Address `json:"address,inline"` 
}

// v1

 {
  "name": "Lucky",
  "address": {
    "street": "long street"
  }
}

// v2

 {
    "name": "Lucky",
    "street": "long street"
}

性能提升：全新解析器减少反射开销

json/v2 在性能方面也有显著改进，尤其在处理大规模 JSON 数据时表现更为出色。这主要归功于其重新设计的解析器，采用状态机架构并大幅减少对反射机制的依赖，从而降低了解析过程中的计算开销和内存占用。

json v2 有哪些配置?

提示

配置选项说明
FormatNilMapAsNull定义如何编码空映射（nil maps）
FormatNilSliceAsNull定义如何编码空切片（nil slices）
MatchCaseInsensitiveNames允许名称大小写不敏感匹配（如 Name ↔ name 等情况）
Multiline将 JSON 对象展开为多行
OmitZeroStructFields从输出中省略具有零值的字段
SpaceAfterColon在每个冒号（:）后添加空格
SpaceAfterComma在每个逗号（,）后添加空格
StringifyNumbers将数值类型表示为字符串
WithIndent缩进嵌套属性（注意：MarshalIndent 函数已被移除）
WithIndentPrefix缩进嵌套属性（注意：MarshalIndent 函数已被移除）

例子


alice := Person{Name: "Alice", Age: 25}
b, _ := json.Marshal(
    alice,
    json.OmitZeroStructFields(true),
    json.StringifyNumbers(true),
    jsontext.WithIndent("  "),
)
fmt.Println(string(b))
最近更新
贡献者: Ryan Su