用 Decoder 流式解析超大 JSON 数组并控制内存峰值

解析超大 JSON 数组时，不要先用 os.ReadFile 或 io.ReadAll 把文件全部装进 []byte，再一次性 json.Unmarshal 到切片。更稳妥的方式是把文件或请求体交给 json.Decoder，先确认顶层是数组，再通过 More 和 Decode 一次处理一个元素。这样内存主要由解码器缓冲、当前元素和下游处理决定，不再随整个数组长度线性增长。

流式解码解决的是“不要同时保留整个输入和全部对象”，但它不会自动限制输入大小，也不能阻止单个元素过大或下游把所有结果重新聚合进内存。

问题现场：文件越大，内存为什么涨得越快

很多导入程序最初都从下面的写法开始。它适合小文件，但面对数 GB 的数组时，data 保存完整输入，items 又保存全部解码结果；字符串、切片和映射字段还会继续分配。峰值因此不只是文件大小本身。

data, err := os.ReadFile("items.json") // 一次把完整文件读入内存
if err != nil {
    return err
}

var items []Item
if err := json.Unmarshal(data, &items); err != nil { // 再保留全部解码对象
    return err
}
return saveAll(items) // 下游若继续聚合，峰值还会增加

第一步判断很简单：业务真的需要随机访问所有元素吗？如果每条记录都可以独立校验、写库、发送消息或汇总计数，就没有必要构造完整的 []Item。

数组为什么能逐项解码

json.NewDecoder 接受任意 io.Reader，会维护自己的内部缓冲。Token 可以读出数组或对象分隔符，More 报告当前数组或对象中是否还有元素，Decode 则把下一个 JSON 值绑定到目标变量。它们组合后，程序只需保留当前 Item。

下面先写一个只负责解析的函数。开始符、结束符和尾随内容都要检查，不能只在 More 返回 false 时直接结束。

package importjson

import (
    "encoding/json"
    "errors"
    "fmt"
    "io"
)

type Item struct {
    ID    int64  `json:"id"`
    Name  string `json:"name"`
    Price int64  `json:"price"`
}

func decodeArray(r io.Reader, handle func(Item) error) error {
    dec := json.NewDecoder(r)
    dec.DisallowUnknownFields() // 输入字段拼错时立即报错，避免静默丢数据

    token, err := dec.Token()
    if err != nil {
        return fmt.Errorf("读取数组开始符失败: %w", err)
    }
    start, ok := token.(json.Delim)
    if !ok || start != '[' { // 明确要求顶层必须是 JSON 数组
        return errors.New("顶层 JSON 必须是数组")
    }

    var item Item
    for index := 0; dec.More(); index++ {
        item = Item{} // 清除上一项字段，避免可选字段沿用旧值
        if err := dec.Decode(&item); err != nil {
            return fmt.Errorf("第 %d 项解析失败，偏移 %d: %w",
                index, dec.InputOffset(), err) // 记录偏移便于定位坏数据
        }
        if err := handle(item); err != nil {
            return fmt.Errorf("第 %d 项处理失败: %w", index, err)
        }
    }

    token, err = dec.Token()
    if err != nil {
        return fmt.Errorf("读取数组结束符失败: %w", err)
    }
    end, ok := token.(json.Delim)
    if !ok || end != ']' { // More 为 false 后仍要消费并核对结束符
        return errors.New("JSON 数组没有正确闭合")
    }

    if _, err := dec.Token(); !errors.Is(err, io.EOF) {
        if err == nil {
            return errors.New("数组后存在额外 JSON 值")
        }
        return fmt.Errorf("数组后存在非法内容: %w", err)
    }
    return nil
}

把文件处理改成“解一条、处理一条”

解析函数只保证结构正确，真正决定内存是否稳定的是 handle。如果回调把每个元素再次追加到全局切片，流式读取就失去了意义。更合适的做法是按单条或固定小批次提交，并让批次容量保持不变。

func importFile(path string) error {
    file, err := os.Open(path)
    if err != nil {
        return err
    }
    defer file.Close() // 无论解析成功或失败都释放文件描述符

    return decodeArray(file, func(item Item) error {
        if item.ID 

如果逐条写数据库开销太高，可以维护一个固定容量的小批次，例如 500 条，写完后把切片长度重置为 0 并复用底层数组。批次大小应由下游吞吐和单项体积决定，而不是由文件总行数决定。

流式解析仍要补齐输入与错误边界

Decoder 会缓冲，也可能从底层 Reader 多读一些数据；“流式”并不表示输入无限大也没关系。文件导入可以先检查文件元数据，HTTP 接口可以使用 http.MaxBytesReader。面对普通 io.Reader，可以给 io.LimitedReader 多留一个字节，用于区分刚好达到上限与已经超限。

var ErrInputTooLarge = errors.New("JSON 输入超过上限")

func decodeWithLimit(src io.Reader, maxBytes int64, handle func(Item) error) error {
    limited := &io.LimitedReader{
        R: src,
        N: maxBytes + 1, // 多允许 1 字节，用来判断输入是否真正越界
    }

    err := decodeArray(limited, handle)
    if limited.N == 0 { // 已经读取到额外的第 1 个字节
        return ErrInputTooLarge
    }
    return err
}

这个限制覆盖的是整个 JSON 字节流。若单个元素本身包含巨大的字符串或嵌套数组，当前元素仍可能占用大量内存，因此还要对字段长度、嵌套深度和业务允许的数据量设置约束。标准库的 DisallowUnknownFields 能阻止未知对象字段，但不会替你完成这些业务规则。

错误偏移能帮你定位什么

InputOffset 返回当前解码位置的字节偏移，可用于错误日志和离线修复。它不是元素编号，也不是底层 Reader 已读取的总字节数，因为 Decoder 可能预读。日志中最好同时记录数组索引、偏移和业务主键，既能快速找到坏数据，也不会误把内部缓冲量当成处理进度。

怎样确认内存真的被控制住

不要只把 Unmarshal 换成 Decoder 就结束。沿着数据生命周期继续检查：

• 输入层没有 ReadAll、os.ReadFile 或无限增长的 bytes.Buffer。
• 循环里只保留当前元素，或只保留容量固定的小批次。
• 处理函数不会把指针、字符串或原始 JSON 长期追加到全局集合。
• 数组开始符、结束符和尾随内容都被检查，截断文件不会被当成成功。
• 文件、HTTP 请求体和单项字段都有清晰上限。
• 处理失败时能按数组索引、输入偏移和业务标识定位，而不是重新加载整个文件。

如果这些条件都成立，内存峰值通常由“Decoder 内部缓冲 + 当前 Item + 固定小批次 + 下游客户端缓冲”构成。即使数组元素数量继续增加，程序也不必保留已经处理完成的对象。

常见问题

Decoder 会不会一次把整个文件读完？ 不会为了一个 Decode 主动构造完整数组，但它有自己的缓冲，并可能从 Reader 预读超过当前值所需的字节，因此不要用底层读取量代替处理进度。

为什么要先读 Token('[')？ 因为直接循环 Decode 无法表达“顶层必须是数组”的结构契约。显式检查分隔符还能在对象、单值或截断输入时更早给出明确错误。

可以并发处理每个元素吗？ 可以，但要使用有界 worker 队列。无界 goroutine 会把大量尚未处理的 Item 留在内存，再次制造与数组规模相关的峰值。

数字放进 interface{} 后怎样避免变成 float64？ 在需要动态结构时调用 dec.UseNumber()，再按业务要求解析 json.Number；结构体字段已有明确整数类型时不需要这样做。

官方参考

• encoding/json：Decoder
• encoding/json：Decoder.Token
• encoding/json：Decoder.More
• encoding/json：Decoder.InputOffset