使用 json.Decoder 流式逐对象解码第三方 HTTP API 返回的数万条记录 JSON 数组-泛播科技

在外部数据同步任务中，第三方 HTTP API 常返回包含数万条记录的 JSON 数组。传统方式先将完整响应体读取为字节切片，再调用 json.Unmarshal 将其转为结构体切片，会导致程序在处理过程中同时持有原始字节数据和所有解码后的对象，内存占用迅速攀升。

流式处理通过 json.Decoder 从 io.Reader 中按需读取和解码，每次只处理单个记录对象。HTTP 响应的 Body 实现了 io.Reader 接口，因此可直接传入 Decoder。解码完成后立即处理该记录（例如持久化到存储），不累积所有对象到内存中的切片。这样，程序在面对大型响应时，内存使用保持稳定，不会因记录数量增加而出现过高峰值。

json.Decoder 的核心方法包括 Token、More 和 Decode。Token 用于消费 JSON 结构中的分隔符，如数组起始的“[”。More 方法返回布尔值，指示当前数组中是否还有未读取的元素。Decode 则将下一个完整对象填充到提供的结构体指针中。这些操作均基于流式读取，仅在必要时从网络缓冲区拉取数据。

以下是完整、可独立运行的最小示例，使用 net/http、encoding/json、net/http/httptest 和 io 等标准库。示例包含一个模拟第三方 API 的 httptest 服务器和对应的客户端处理函数。代码标注为 Go 1.22 版本，所有 error 均被显式检查和包装，包括响应 Body 的关闭错误、Token 错误、Decode 错误以及状态码检查。处理函数使用具名返回值以确保关闭错误能在不覆盖原有错误时被传播。

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"net/http/httptest"
)

type Record struct {
	ID   int    json:&quot;id&quot;
	Name string json:&quot;name&quot;
}

func processLargeResponse(url string) (err error) {
	resp, err := http.Get(url)
	if err != nil {
		return fmt.Errorf("http get failed: %w", err)
	}
	defer func() {
		if cerr := resp.Body.Close(); cerr != nil && err == nil {
			err = fmt.Errorf("close body failed: %w", cerr)
		}
	}()
	if resp.StatusCode != http.StatusOK {
		return fmt.Errorf("bad status code: %d", resp.StatusCode)
	}
	decoder := json.NewDecoder(resp.Body)
	tok, err := decoder.Token()
	if err != nil {
		return fmt.Errorf("read array start token failed: %w", err)
	}
	if d, ok := tok.(json.Delim); !ok || d != '[' {
		return fmt.Errorf("expected array start, got %v", tok)
	}
	count := 0
	for decoder.More() {
		var r Record
		if err = decoder.Decode(&r); err != nil {
			return fmt.Errorf("decode record failed: %w", err)
		}
		count++
	}
	_, err = decoder.Token()
	if err != nil {
		return fmt.Errorf("read array end token failed: %w", err)
	}
	fmt.Printf("成功处理 %d 条记录\n", count)
	return nil
}

上述函数聚焦流式解码核心逻辑。在实际同步任务中，将循环体内的记录处理替换为持久化操作，且不将 Record 追加到任何切片中，以维持低内存占用。服务器部分使用 httptest 模拟返回 JSON 数组，生产环境中替换为真实 API 地址。

func main() {
	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "application/json")
		records := []Record{
			{ID: 1, Name: "Item 1"},
			{ID: 2, Name: "Item 2"},
			{ID: 3, Name: "Item 3"},
		}
		if err := json.NewEncoder(w).Encode(records); err != nil {
			http.Error(w, "encode failed", http.StatusInternalServerError)
			return
		}
	}))
	defer ts.Close()

	if err := processLargeResponse(ts.URL); err != nil {
		fmt.Printf("处理错误: %v\n", err)
		return
	}
}

运行上述完整程序会输出处理记录数。服务器端使用 json.NewEncoder 构造响应，客户端则完全依赖 Decoder 消费流。注意循环结束后仍需消费结束分隔符“]”，以确保流被正确耗尽。

常见误区包括：直接对 resp.Body 调用 json.Unmarshal，这仍需先读取全部内容；忽略 Token 调用，直接在数组根上循环 Decode 会导致类型不匹配错误；未检查每次 Decode 的返回值，导致部分记录解析失败时程序状态不一致；循环内仍将记录累积到切片，抵消了流式优势；忘记处理 resp.Body.Close 的错误，可能造成资源泄漏。

正确用法要求在每次网络或解析调用后立即检查 err，并使用 %w 包装以保留原始错误上下文。流式处理适用于逐条同步的场景，例如将记录依次写入文件或数据库，而无需同时持有全量数据。如果单个记录对象本身体积极大，或业务逻辑必须在内存中完成全数据集计算（如全局去重），则流式解码无法降低内存峰值，此时需评估其他数据获取方式。

通过上述方式，程序在接收大型 JSON 数组响应时，仅在内存中保留当前正在解码的单个对象及少量缓冲区。Decoder 的内部实现按需从 Reader 拉取字节，避免了完整响应体的常驻内存。这让数据同步任务能在资源受限的环境中稳定运行，而不会因响应规模扩大导致内存峰值过高。

总结：在处理第三方 API 返回的数万条记录 JSON 数组的外部数据同步任务中，json.Decoder 的流式逐对象解码通过 Token 消费数组边界、More 判断剩余元素、Decode 填充单个结构体并立即处理，结合完整错误包装和 Body 关闭，确保程序稳定应对大响应。需注意正确处理数组分隔符、避免累积数据结构、检查所有调用返回值。这些边界在示例中均已覆盖，可直接作为生产任务的基础实现模板。建议查阅官方文档确认最新标准库行为。

（全文约 1850 字）

文章版权归作者所有，未经允许请勿转载。

THE END