Go 怎么流式解析超大 JSON 数组而不一次读入内存

如果接口返回的是几百万条记录，先用 io.ReadAll 读完，再把 []byte 交给 json.Unmarshal，内存里至少会同时出现原始字节、数组切片和一批结构体。更稳妥的做法是让 json.Decoder 直接从 io.Reader 读取顶层数组，每次只把一个元素解码到复用的结构体中。

下面的写法只处理“顶层是数组”的 JSON。它不会让整个数组常驻内存，但单个数组元素仍要完整放进 Item；如果某一项本身特别大，还要额外限制输入总字节数或拆分上游格式。

为什么 json.Unmarshal 会把大数组变成内存压力

json.Unmarshal 接收的是已经存在内存里的字节切片。目标如果是 []Item，解码器还会不断扩容切片并保留所有元素，方便后续随机访问。这种方式适合中小型配置文件，却不适合“读取一项、处理一项、处理完就丢掉”的导入任务。

流式方案把边界改成了三层：输入来自 io.Reader，json.Decoder 维护 JSON 游标，业务只持有当前的 Item。因此峰值内存主要跟解码器缓冲、当前元素和业务处理逻辑有关，而不是跟数组总条数线性增长。

用 json.Decoder 逐项消费数组

关键顺序是先读数组开始符，再循环解码，最后读数组结束符。More 只用于当前数组或对象内部，不能拿它判断一个任意 JSON 流是否还有下一段数据。

package main

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

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

func streamItems(r io.Reader) error {
    dec := json.NewDecoder(r)

    // 顶层必须先出现数组开始符，避免把对象误当成数组处理。
    start, err := dec.Token()
    if err != nil {
        return fmt.Errorf("读取数组开始符失败: %w", err)
    }
    if delim, ok := start.(json.Delim); !ok || delim != '[' {
        return fmt.Errorf("期望 JSON 数组，实际得到 %v", start)
    }

    var item Item
    for dec.More() {
        item = Item{}
        // 每轮只覆盖当前元素，处理函数不要把 item 的地址长期保存。
        if err := dec.Decode(&item); err != nil {
            return fmt.Errorf("解码数组元素失败: %w", err)
        }
        fmt.Printf("处理 %s: %s\\n", item.ID, item.Name)
    }

    // 读取数组结束符，确认数组结构完整闭合。
    end, err := dec.Token()
    if err != nil {
        return fmt.Errorf("读取数组结束符失败: %w", err)
    }
    if delim, ok := end.(json.Delim); !ok || delim != ']' {
        return fmt.Errorf("数组没有正常结束: %v", end)
    }
    return nil
}

func main() {
    input := `[{"id":"a-1","name":"键盘","price":199},{"id":"a-2","name":"鼠标","price":89}]`
    if err := streamItems(strings.NewReader(input)); err != nil {
        fmt.Println(err)
    }
}

这里的复用变量不是为了追求极限优化，而是为了让生命周期清楚：循环体结束后不把 &item 放进全局切片、异步队列或缓存。若业务必须异步处理，应复制需要的字段，或把所有权交给明确的任务对象。

把单项大小和输入边界控制好

面对 HTTP 上传或外部文件，建议先决定“最多接收多少字节”。io.LimitReader 限制的是整个输入，不是单个数组元素；它适合防止请求体无限增长。单个元素仍然可能很大，应该通过结构设计、字段长度限制或上游分页来解决。

func importBody(body io.Reader, maxBytes int64) error {
    // 总输入超过上限时，解码过程会在读到边界后报错或提前结束。
    limited := io.LimitReader(body, maxBytes)
    dec := json.NewDecoder(limited)

    token, err := dec.Token()
    if err != nil {
        return fmt.Errorf("读取输入失败: %w", err)
    }
    if delim, ok := token.(json.Delim); !ok || delim != '[' {
        return fmt.Errorf("输入必须是顶层数组")
    }

    var item Item
    for dec.More() {
        item = Item{}
        if err := dec.Decode(&item); err != nil {
            return fmt.Errorf("输入超过上限或 JSON 损坏: %w", err)
        }
        // 在这里写入数据库、发送消息或更新统计，不累积整个数组。
        if err := handleItem(item); err != nil {
            return fmt.Errorf("处理 %s 失败: %w", item.ID, err)
        }
    }
    _, err = dec.Token()
    return err
}

func handleItem(item Item) error {
    // 示例业务函数只保留同步处理边界，不保存 item 的指针。
    return nil
}

如果输入来自网络，读取循环还应配合请求超时、连接关闭和错误日志；如果来自文件，最好让上游按页输出数组，或改成一行一个 JSON 对象。Decoder 解决的是“不要一次物化整个数组”，不会替你完成限流、事务批次和失败重试。

常见坑：空数组、尾部数据与对象过大

严格接口还可以在读取结束后检查尾部是否只有空白。要注意，Decoder 允许连续解码多个 JSON 值，所以“数组已经闭合”不必然等于“整个输入只有一个数组”。是否拒绝尾部对象，应由协议决定，而不是默默忽略。

最后，别把 json.RawMessage 当成自动省内存方案：它会保留原始 JSON 片段，适合延迟解码，不适合把超大元素永久挂在内存里。真正需要降峰时，优先让上游分页，或者让每个对象独立成行并逐行消费。

相关问题

流式解析后还能统计数组总数吗？

可以，在循环中维护计数器；不要为了获取总数再把元素收集到切片。若响应头或协议能提供总数，优先使用协议字段。

能不能直接用 dec.Decode(&items)？

可以，但目标是 []Item 时仍会把数组完整装入内存，失去逐项处理的主要收益。

一个元素很大时该怎么做？

先从协议层拆小对象或分页，再配合输入总量限制；仅把 Unmarshal 换成 Decoder，不能限制单个 JSON 对象的大小。