Go json/v2实战：告别内存爆炸，掌握真流式Marshal和Unmarshal
本文永久链接 – https://tonybai.com/2025/08/09/true-streaming-support-in-jsonv2
大家好，我是Tony Bai。
Go 开发者长期以来面临一个痛点：标准库 encoding/json 在处理大型 JSON 数据时，即使使用 Encoder/Decoder，也因其内部的全量缓冲机制而导致巨大的内存开销。备受期待的 encoding/json/v2 提案（#71497）旨在从根本上解决这一问题。通过引入全新的底层包 encoding/json/jsontext，v2 实现了真正的流式处理能力。本文将通过具体的、可量化的基准测试，向你展示 v1 的内存陷阱，并演示如何使用 json/v2 高效地实现流式处理大规模 JSON 数据，彻底告别内存爆炸的烦恼。
json/v1 的“伪流”之痛：一个内存陷阱基准
为了直观地感受 json/v1 在处理大数据时的局限性，我们来建立一个基准测试。我们将分别进行编码（Marshal）和解码（Unmarshal）操作，并观察其内存使用情况。
关于内存评估：我们通过比较操作前后的 runtime.MemStats.TotalAlloc 来精确测量该操作自身导致的堆内存总分配量。一个真正的流式处理，其内存分配量应该是一个很小的常数（例如，I/O 缓冲区的大小），而与数据总量无关。
场景一：v1 编码一个巨大的 JSON 数组
我们创建一个包含 100 万个空结构体的 slice，然后使用 json.Encoder 将其写入 io.Discard。
// jsonv2-streaming/v1/marshal.go
package main
import (
"encoding/json"
"io"
"log"
"runtime"
)
func main() {
const numRecords = 1_000_000
in := make([]struct{}, numRecords)
out := io.Discard
// 多次 GC 以清理 sync.Pools，确保测量准确
for i := 0; i < 5; i++ {
runtime.GC()
}
var statsBefore runtime.MemStats
runtime.ReadMemStats(&statsBefore)
log.Println("Starting to encode with json/v1...")
encoder := json.NewEncoder(out)
if err := encoder.Encode(&in); err != nil {
log.Fatalf("v1 Encode failed: %v", err)
}
log.Println("Encode finished.")
var statsAfter runtime.MemStats
runtime.ReadMemStats(&statsAfter)
allocBytes := statsAfter.TotalAlloc - statsBefore.TotalAlloc
log.Printf("Total bytes allocated during Encode: %d bytes (%.2f MiB)", allocBytes, float64(allocBytes)/1024/1024)
}
分析：当你运行此程序，会看到总分配字节数是一个巨大的数字，通常是几兆字节 (MiB)。这是因为 json.Encoder 必须先在内存中将整个 slice 序列化成一个完整的、约几MB（{} 乘以 100 万）的 JSON 字符串，然后才开始写入。这个巨大的字符串就是内存分配的来源。
在我的Mac上，这个程序的输出如下：
$go run unmarshal.go
2025/08/09 13:38:47 Starting to decode with json/v1...
2025/08/09 13:38:47 Decode finished.
2025/08/09 13:38:47 Total bytes allocated during Decode: 8394096 bytes (8.01 MiB)
下面再来看看v1版本的json解码。
场景二：v1 解码一个巨大的 JSON 数组
现在，我们构造一个代表百万空对象的 JSON 字符串，并使用 json.Decoder 解码。
// jsonv2-streaming/v1/unmarshal.go
package main
import (
"encoding/json"
"log"
"runtime"
"strings"
)
func main() {
const numRecords = 1_000_000
// 构造一个巨大的 JSON 数组字符串，约 2MB
value := "[" + strings.TrimSuffix(strings.Repeat("{},", numRecords), ",") + "]"
in := strings.NewReader(value)
// 预分配 slice 容量，以排除 slice 自身扩容对内存测量的影响
out := make([]struct{}, 0, numRecords)
for i := 0; i < 5; i++ {
runtime.GC()
}
var statsBefore runtime.MemStats
runtime.ReadMemStats(&statsBefore)
log.Println("Starting to decode with json/v1...")
decoder := json.NewDecoder(in)
if err := decoder.Decode(&out); err != nil {
log.Fatalf("v1 Decode failed: %v", err)
}
log.Println("Decode finished.")
var statsAfter runtime.MemStats
runtime.ReadMemStats(&statsAfter)
allocBytes := statsAfter.TotalAlloc - statsBefore.TotalAlloc
log.Printf("Total bytes allocated during Decode: %d bytes (%.2f MiB)", allocBytes, float64(allocBytes)/1024/1024)
}
分析：同样，你会看到数兆字节的内存分配。json.Decoder 在反序列化之前，会将整个 JSON 数组作为一个单独的值完整地读入其内部缓冲区。这个缓冲区的大小与输入数据的大小成正比。
运行该代码，我机器上的输出如下：
$go run unmarshal.go
2025/08/09 13:38:47 Starting to decode with json/v1...
2025/08/09 13:38:47 Decode finished.
2025/08/09 13:38:47 Total bytes allocated during Decode: 8394096 bytes (8.01 MiB)
从上面两个例子，我们看到：json/v1 的 Encoder 和 Decoder 提供的只是API 层面的流式抽象，其底层实现是全量缓冲的，导致内存复杂度和数据大小成线性关系 (O(N))。这就是“伪流”之痛。
json/v2 的革命：用正确的 API 实现真流式处理
现在，让我们见证 json/v2 的魔力。我们将使用 v2 推荐的流式 API，来完成与 v1 示例完全相同的任务，并进行内存对比。
场景一：v2 流式编码一个巨大的 JSON 数组
我们将模拟从数据源逐条获取数据，并使用 jsontext.Encoder 手动构建 JSON 数组流。
// jsonv2-streaming/v2/marshal.go
package main
import (
"io"
"log"
"runtime"
"encoding/json/v2"
"encoding/json/jsontext"
)
func main() {
const numRecords = 1_000_000
out := io.Discard
for i := 0; i < 5; i++ {
runtime.GC()
}
var statsBefore runtime.MemStats
runtime.ReadMemStats(&statsBefore)
log.Println("Starting to encode with json/v2...")
enc := jsontext.NewEncoder(out)
// 手动写入数组开始标记
if err := enc.WriteToken(jsontext.BeginArray); err != nil {
log.Fatalf("Failed to write array start: %v", err)
}
// 逐个编码元素
for i := 0; i < numRecords; i++ {
// 内存中只需要一个空结构体，几乎不占空间
record := struct{}{}
if err := json.MarshalEncode(enc, record); err != nil {
log.Fatalf("v2 MarshalEncode failed for record %d: %v", i, err)
}
}
// 手动写入数组结束标记
if err := enc.WriteToken(jsontext.EndArray); err != nil {
log.Fatalf("Failed to write array end: %v", err)
}
log.Println("Encode finished.")
var statsAfter runtime.MemStats
runtime.ReadMemStats(&statsAfter)
allocBytes := statsAfter.TotalAlloc - statsBefore.TotalAlloc
log.Printf("Total bytes allocated during Encode: %d bytes (%.2f KiB)", allocBytes, float64(allocBytes)/1024)
}
分析：运行此程序，你会看到总分配字节数是一个非常小的数字，通常是几十千字节 (KiB)，主要用于 Encoder 内部的 I/O 缓冲。v2 将每个元素编码后立即写入，没有在内存中构建那个 2MB 的巨大字符串。
在我的机器上运行该示例，编码过程实际分配的内存仅有不到15KB：
$GOEXPERIMENT=jsonv2 go run marshal.go
2025/08/09 13:45:50 Starting to encode with json/v2...
2025/08/09 13:45:50 Encode finished.
2025/08/09 13:45:50 Total bytes allocated during Encode: 15328 bytes (14.97 KiB)
场景二：v2 流式解码一个巨大的 JSON 数组
我们将使用 jsontext.Decoder 和 jsonv2.UnmarshalDecode 的组合来逐个解码元素。
// jsonv2-streaming/v2/unmarshal.go
package main
import (
"errors"
"io"
"log"
"runtime"
"strings"
"encoding/json/v2"
"encoding/json/jsontext"
)
func main() {
const numRecords = 1_000_000
value := "[" + strings.TrimSuffix(strings.Repeat("{},", numRecords), ",") + "]"
in := strings.NewReader(value)
_ = make([]struct{}, 0, numRecords) // out 变量在实际应用中会用到
for i := 0; i < 5; i++ {
runtime.GC()
}
var statsBefore runtime.MemStats
runtime.ReadMemStats(&statsBefore)
log.Println("Starting to decode with json/v2...")
dec := jsontext.NewDecoder(in)
// 手动读取数组开始标记 '['
tok, err := dec.ReadToken()
if err != nil || tok.Kind() != '[' {
log.Fatalf("Expected array start, got %v, err: %v", tok, err)
}
// 循环解码数组中的每个元素
for dec.PeekKind() != ']' {
var record struct{}
if err := json.UnmarshalDecode(dec, &record); err != nil {
if errors.Is(err, io.EOF) {
break
}
log.Fatalf("v2 UnmarshalDecode failed: %v", err)
}
// 在实际应用中，这里会处理 record，例如：
// out = append(out, record)
}
log.Println("Decode finished.")
var statsAfter runtime.MemStats
runtime.ReadMemStats(&statsAfter)
allocBytes := statsAfter.TotalAlloc - statsBefore.TotalAlloc
log.Printf("Total bytes allocated during Decode: %d bytes (%.2f KiB)", allocBytes, float64(allocBytes)/1024)
}
分析：同样，你会看到总分配字节数非常小。UnmarshalDecode 在循环中每次只读取并解码一个 {} 对象，而 jsontext.Decoder 的内部缓冲区大小是固定的，不会因输入流的增大而膨胀。
下面是我机器上运行的结果，和v2编码一样，仅需要15KB左右的缓冲区：
$ GOEXPERIMENT=jsonv2 go run unmarshal.go
2025/08/09 13:55:29 Starting to decode with json/v2...
2025/08/09 13:55:29 Decode finished.
2025/08/09 13:55:29 Total bytes allocated during Decode: 15248 bytes (14.89 KiB)
内存占用对比总结
| 操作 | json/v1 (伪流) 内存分配 | json/v2 (真流) 内存分配 | 结论 |
|---|---|---|---|
| Marshal | ~8 MiB (与数据大小成正比) | ~15 KiB (固定开销) | 数量级差异 |
| Unmarshal | ~8 MiB (与数据大小成正比) | ~15 KiB (固定开销) | 数量级差异 |
这个直接的、数据驱动的对比，无可辩驳地证明了 json/v2 在流式处理方面的革命性突破。它将内存复杂度从 O(N) 降低到了 O(1)，为 Go 语言处理海量 JSON 数据铺平了道路。
正如提出issue #33714的开发者flimzy所说的那样：json/v2正是json流处理的答案！
小结
encoding/json/v2 的提案和实现，标志着 Go 在大规模数据处理能力上的一个巨大飞跃。通过将语法和语义分离，并提供底层的、真正的流式 API，v2 彻底解决了 v1 长期存在的内存瓶颈问题。
对于 Go 开发者而言，这意味着：
- 处理超大规模 JSON 不再是难题**：无论是生成还是解析 GB 级别的 JSON 文件或流，都将变得轻而易举，且内存占用可控。
- 更高的性能和效率：根据 v2 的基准测试，新的实现在解码（Unmarshal）方面比 v1 有 2.7 到 10.2 倍的性能提升。
- 更灵活的控制力：底层的 jsontext 包为需要进行精细化 JSON 操作的开发者提供了前所未有的能力。
虽然 Go 1.25 json/v2 会以 GOEXPERIMENT 形式落地，但它所展示的强大能力和优秀设计，已经预示了Go JSON 处理的新纪元。我们有充分的理由期待它在未来的 Go 版本中正式发布，成为所有 Go 开发者处理 JSON 数据的首选工具。
本文涉及的示例代码可以在这里下载。
你的Go技能，是否也卡在了“熟练”到“精通”的瓶颈期？
- 想写出更地道、更健壮的Go代码，却总在细节上踩坑？
- 渴望提升软件设计能力，驾驭复杂Go项目却缺乏章法？
- 想打造生产级的Go服务，却在工程化实践中屡屡受挫？
继《Go语言第一课》后，我的《Go语言进阶课》终于在极客时间与大家见面了！
我的全新极客时间专栏 《Tony Bai·Go语言进阶课》就是为这样的你量身打造！30+讲硬核内容，带你夯实语法认知，提升设计思维，锻造工程实践能力，更有实战项目串讲。
目标只有一个：助你完成从“Go熟练工”到“Go专家”的蜕变！ 现在就加入，让你的Go技能再上一个新台阶！
商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。如有需求，请扫描下方公众号二维码，与我私信联系。
评论