内存不超标：如何在 Go 中流式处理超大 JSON 文件？

在后台系统开发中，处理 GB 级别的超大 JSON 数据（例如数据库备份归档或第三方系统导出的海量日志）是一个常见的性能挑战。如果直接使用 Go 语言标准库中的 json.Unmarshal 进行一次性解析，程序会将整份 JSON 数据全部加载并缓存在内存中。这种“黑洞效应”极易导致系统内存瞬间暴涨，甚至被操作系统触发 OOM 强制杀死。

为了在极低资源占用下平稳处理大规模数据，利用 Go 语言内置的流式解析机制是最优的工程方案。

json.Unmarshal 内存占用的黑洞效应

在解析小型 JSON 数据时，直接读取整个文件并反序列化非常方便。然而，当文件大小达到数吉字节时，常规做法的局限性暴露无遗：

   // 坏味道：一次性读取大文件解析
data, _ := os.ReadFile("large_data.json")
var records []Record
_ = json.Unmarshal(data, &records)

这段代码看似简单，但它要求系统必须拥有比文件体积更大的连续内存空间。即使系统的物理内存足够大，在极短时间内分配和释放数吉字节的内存，也会给 Go 语言的垃圾回收器带来沉重的扫描负担，引发长时间的系统停顿。

json.Decoder 的流式解析原理

解决这一痛点的关键在于将“整读”转为“渐读”。Go 语言标准库中的 json.Decoder 提供了一个基于 io.Reader 的流式接口。它不需要一次性将所有字节加载到内存中，而是可以像水流一样，一边从底层读取输入流，一边解析并产出对应的结构体对象。

在处理包含海量元素的 JSON 数组时，json.Decoder 能够以极其稳定的内存曲线，逐个处理数组中的元素。

实战演练：在极低内存下解析超大数组

要以流式处理一个巨大的 JSON 数组，关键在于配合使用 json.Decoder.Token() 方法和 Decode() 方法。

首先，初始化解码器并读取数组的起始符号 [：

   dec := json.NewDecoder(file)
t, err := dec.Token()
if err != nil || t != json.Delim('[') {
    log.Fatal("expected array start delimiter")
}

这里通过 dec.Token() 提取 JSON 流中的下一个标记。如果是数组，它的第一个 Token 必须是代表数组起始的 [ 分隔符。

接着，利用 dec.More() 在循环中渐进式地读取并解析每一个元素：

   for dec.More() {
    var r Record
    if err := dec.Decode(&r); err != nil {
        log.Fatal(err)
    }
    process(r) // 处理解析完成的单条记录
}

在循环内部，dec.More() 会探测当前数组中是否还有未解析的元素。如果存在，调用 dec.Decode(&r) 会仅仅读取并解析这一个元素的字节，将其反序列化到 Record 结构体中。

在解析并处理完毕后，垃圾回收器可以及时回收单个结构体的内存，从而将系统的整体内存占用牢牢控制在极低的阈值（例如 10 MB 以内）。

最后，在循环结束后，读取并校验数组的结束符号 ]：

   t, err = dec.Token()
if err != nil || t != json.Delim(']') {
    log.Fatal("expected array end delimiter")
}

通过这种流式配合，无论是 1 GB 还是 10 GB 的巨型 JSON 数组，都可以在内存占用几乎平置的曲线下完成处理。

典型应用场景

在日常开发中，以下场景都非常适合采用 json.Decoder 进行流式解析：

• 海量日志与审计数据分析：如服务器日志或安全审计轨迹，往往以巨大的 JSON 数组形式归档，通过流式解析可以逐条过滤分析。
• 数据库备份与数据导入导出：NoSQL 数据库（如 MongoDB）或系统备份导出的 GB 级 JSON 备份集，流式处理可以平稳地将数据逐条入库。
• 第三方大文件 API 对接：对接一些大数据服务或开放平台时，其返回的响应数据可能包含数十万条记录，流式接收并处理可以避免进程因内存暴涨而崩溃。
• 实时监控与事件流订阅：从 HTTP Chunked 响应或 WebSocket 订阅的持续 JSON 事件流中，使用 json.Decoder 进行不间断的流式解析。
• 边缘设备与嵌入式开发：在内存极度受限（如仅数十兆）的物联网边缘设备或轻量级容器中解析配置或结构化上报数据，流式处理是保障系统存活的唯一手段。
• 大模型流式输出解析：解析大模型流式（Stream）返回的 JSON 结构化数据（如 Tool Calls），在接收端逐个字符流式读取并还原结构。

写在最后

虽然流式解析性能优异，但在实际工程落地中，仍需注意以下两点细节：

第一，确保底层的 Reader 具有流式属性。在初始化 json.NewDecoder 时，传入的必须是具备真正流式读取能力的实现，如 *os.File 或 net.Conn。如果是使用 bytes.NewReader(data) 包装已经全部读入内存的切片，流式解析的内存优化效果将大打折扣。

第二，注意数据吞吐速率的平衡。由于流式解析是逐个解析并同步处理，如果单条数据的处理逻辑（如数据库写入、外部 HTTP 接口调用）过于缓慢，可能会导致底层连接的 TCP 缓冲区堆积。在超高并发场景下，建议使用生产者-消费者模式，通过带缓冲的 channel 将解析和数据消费进行解耦。