Go 处理超大 JSON 怎么降峰值内存：json.Decoder 流式读取、批次落库与压测对比

订单导入接口拿到一份 680MiB 的 JSON 数组，第一版代码写得很直白：io.ReadAll 后交给 json.Unmarshal。功能跑起来完全没问题，但压测时 HeapAlloc 很快就冲到 812MiB，容器在并发导入场景下直接被资源调度策略挤压触发限流。这里最容易被忽略的点是：原始输入字节、解码后的结构体、切片扩容产生的冗余空间，加上后续生成的批次切片，很可能会在同一时间共存。数据量上来之后，问题根本不是JSON能不能解析，而是这些对象能不能做到错峰存活。

先看基线：为什么 680MiB 文件会顶到 812MiB

导入任务启动时，文件内容本身还停留在读取缓冲里；io.ReadAll 生成一份完整的连续字节；json.Unmarshal 再创建出完整的 []Order 与对应的字段字符串。如果解析完还要按1000条一批写入数据库，业务代码通常又会额外保留一个批次切片。内存峰值从来不会正好等于文件大小，结构体额外字段、字符串复制操作和切片预分配的容量都会占用额外空间。

type Order struct {
    ID       string `json:"id"`
    UserID   string `json:"user_id"`
    Amount   int64  `json:"amount"`
    Created  string `json:"created_at"`
}

func decodeAll(r io.Reader) ([]Order, error) {
    data, err := io.ReadAll(r)
    if err != nil {
        return nil, err
    }
    var orders []Order
    if err := json.Unmarshal(data, &orders); err != nil {
        return nil, err
    }
    return orders, nil
}

这种写法对付几十 KB 的请求非常顺手，接口逻辑简单、错误返回信息也足够清晰。但一旦输入换成大体积数组，data 和 orders 的生命周期出现大面积交叠，内存曲线就很容易出现陡峭的单峰。不用上来就急着调整GC参数，如果这些对象本来就要求必须同时存活，调参最多只能改变回收时机，不可能凭空把峰值压下来。

把整段 JSON 换成流式 Token 读取

当输入的根节点是 JSON 数组时，json.Decoder 可以先读掉开头的 [，再在 More() 条件满足时逐条 Decode。这不是要把原有JSON格式改成JSONL，整个流程仍然接收标准的JSON数组，只是不再要求把整个数组先完整加载到一个Go切片里。

func streamOrders(r io.Reader, handle func(Order) error) error {
    dec := json.NewDecoder(r)

    tok, err := dec.Token()
    if err != nil {
        return fmt.Errorf("read array start: %w", err)
    }
    if d, ok := tok.(json.Delim); !ok || d != '[' {
        return fmt.Errorf("expected JSON array")
    }

    line := 0
    for dec.More() {
        line++
        var item Order
        if err := dec.Decode(&item); err != nil {
            return fmt.Errorf("decode item %d: %w", line, err)
        }
        if err := handle(item); err != nil {
            return fmt.Errorf("handle item %d: %w", line, err)
        }
    }

    tok, err = dec.Token()
    if err != nil {
        return fmt.Errorf("read array end: %w", err)
    }
    if d, ok := tok.(json.Delim); !ok || d != ']' {
        return fmt.Errorf("expected JSON array end")
    }
    return nil
}

这里的 line 实际是数组内的元素序号，不是文本行号，但已经足够把“某处JSON解析失败”的范围缩小到具体的某条记录。如果上游数据源能提供业务主键，也可以在解码成功后一起写入错误日志。这个小优化对回放失败样本帮助很大，尤其是导入任务跑了十几分钟之后才碰到一条脏数据的场景。

改动点不只在 Decoder：批次大小决定留下多少对象

逐条解码之后立刻写库当然最省内存，但会把数据库往返次数放大到完全无法接受的程度。更常用的折中方案是可控批次处理：每读到1000条就提交一次写入，之后把批次切片里的元素置空，直接复用切片本身的容量。不用上来就把1000当成固定最优值，如果单条记录里包含超大字段、写入端性能偏慢，设成200条一批反而更稳定。

func importOrders(r io.Reader, saveBatch func([]Order) error) error {
    const batchSize = 1000
    batch := make([]Order, 0, batchSize)

    flush := func() error {
        if len(batch) == 0 {
            return nil
        }
        if err := saveBatch(batch); err != nil {
            return err
        }
        for i := range batch {
            batch[i] = Order{}
        }
        batch = batch[:0]
        return nil
    }

    if err := streamOrders(r, func(item Order) error {
        batch = append(batch, item)
        if len(batch) == batchSize {
            return flush()
        }
        return nil
    }); err != nil {
        return err
    }
    return flush()
}

清空元素的目的不是制造“内存立刻归零”的假象，而是避免批次底层的数组空间继续把字符串这类引用带到下一轮循环里。如果 saveBatch 会异步持有 batch，那就不能在调用返回后直接复用这批数据：要么让存储函数完成同步写入之后再返回，要么复制整批数据明确交接所有权。内存优化不能靠赌调用方不会偷偷留引用。

压测时别只看耗时：同时记录峰值堆与错误行

改成流式读取之后，符合预期的指标不是某个特别好看的单次耗时，而是峰值堆大小不再随着输入总大小近似线性上涨。可以用同一份样本分别跑完整解码和流式解码两套逻辑，记录每一轮的 HeapAlloc、NumGC、总耗时、成功处理条数以及第一个出现错误的元素位置。测试环境里可以用 go test -bench 或者独立命令重复跑多轮，不要只拿第一次的冷启动数据直接下结论。

func memSnapshot() runtime.MemStats {
    var m runtime.MemStats
    runtime.ReadMemStats(&m)
    return m
}

// 在导入前后记录：m.HeapAlloc、m.TotalAlloc、m.NumGC。
// 若业务允许，可在样本之间留出空闲窗口观察稳定期，
// 但不要在每个请求路径里强制 runtime.GC()。

本地测试样本从整段加载改成单元素解码、1000条同步批次之后，峰值堆不再由680MiB的文件整体决定；真正的内存上限会接近“单条对象+当前批次+写入端短暂缓冲”的总和。这是架构层面的结构性变化，不会保证每台机器都得到完全一致的优化比例。字段平均长度、数据库驱动缓存、压缩读取逻辑和并发数都会让最终的内存曲线产生差异。

几个容易踩到的边界

• 根节点不是数组怎么办？如果顶层是对象，应该先按协议读取外层对象字段，定位到目标数组字段之后再逐项解码；不要默认所有JSON都能直接用 More() 循环处理。
• 能否用 DisallowUnknownFields？可以。它更适合接口契约非常严格的导入场景，但要提前确认上游不会额外携带兼容字段，不然线上失败率会毫无征兆地突然上升。
• 批次越大越快吗？不一定。批次变大确实可能减少写入次数，但也会同时增加对象留存时间、事务耗时和失败重试的成本。
• 流式读取能处理半截文件吗？它可以更早发现格式错误，但没办法把不完整的数组变成合法成功数据。流程里必须保留失败元素序号和任务标识，方便后续重新投递处理。

延伸问答

json.Decoder 和 json.Unmarshal 应该怎么选？

小请求、配置文件和确实需要拿到完整结果切片的场景，用 json.Unmarshal 更直接。输入体量很大、结果可以边读边处理的场景，json.Decoder 更方便控制峰值内存。

流式解码会不会比一次性解码慢？

它确实多了逐项处理与函数调用的小开销，但省下来的大规模内存分配、数据复制和GC压力带来的收益通常要大得多。应该用自己业务的实际字段、批次大小和并发数做基准测试，不要只对比一轮的耗时就下判断。

批次切片为什么要把元素置空？

切片长度归零只会改变对外可见的元素范围，底层数组仍然可能留存元素字段里的指针。把已经处理完的元素置为零值，能减少旧字符串和切片被下一轮容量复用时继续持有的概率。

遇到单条坏 JSON 要不要跳过继续导入？

这取决于业务的一致性要求。订单、账务这类关键数据通常应该直接停止并回滚；允许部分成功的批处理场景，可以记录对应元素序号、错误原因和原始任务标识，再把失败项交给人工或者补偿流程处理。

收尾：让输入大小不再直接决定堆峰值

处理超大 JSON 导入的第一步不是去调GC参数，而是减少“整份输入、完整结果和待写批次同时存活”的时间窗口。用 json.Decoder 逐项读取数据，用业务能承受的批次边界提交写入，用元素序号记录异常信息，再用峰值堆指标和多轮压测复核结果，导入接口才能从靠运气不出事的逻辑，变成可以明确解释资源消耗的可控流程。