Go JSON 流式处理入门：不用一次把大文件读进内存

大 JSON 不应该总是 ReadAll

很多入门代码会这样解析 JSON：

data, err := io.ReadAll(r)
if err != nil {
	return err
}

var users []User
if err := json.Unmarshal(data, &users); err != nil {
	return err
}

小数据没问题，但如果请求体或文件很大，这会一次性把所有内容读进内存。导入几万行用户、处理日志导出、读取大数组时，更好的方式是使用 json.Decoder 流式处理。它可以从 io.Reader 一边读一边解码，不必先把全部数据变成 []byte。

这篇文章讲大 JSON 数组的流式读取，以及如何逐条写出 JSON。

逐个读取数组元素

假设 JSON 文件是一个数组：

[
  {"email":"a@example.com","name":"小林"},
  {"email":"b@example.com","name":"阿周"}
]

结构体：

type User struct {
	Email string `json:"email"`
	Name  string `json:"name"`
}

流式读取：

func ImportUsers(r io.Reader, handle func(User) error) error {
	decoder := json.NewDecoder(r)

	token, err := decoder.Token()
	if err != nil {
		return fmt.Errorf("read start token: %w", err)
	}
	if token != json.Delim('[') {
		return fmt.Errorf("expected json array")
	}

	for decoder.More() {
		var user User
		if err := decoder.Decode(&user); err != nil {
			return fmt.Errorf("decode user: %w", err)
		}
		if err := handle(user); err != nil {
			return err
		}
	}

	token, err = decoder.Token()
	if err != nil {
		return fmt.Errorf("read end token: %w", err)
	}
	if token != json.Delim(']') {
		return fmt.Errorf("expected array end")
	}
	return nil
}

调用：

file, err := os.Open("users.json")
if err != nil {
	return err
}
defer file.Close()

err = ImportUsers(file, func(user User) error {
	fmt.Println(user.Email)
	return nil
})

这样处理大文件时，内存压力会小很多。

边读边批量写数据库

真实导入时，你可能不想每条都写一次数据库，而是批量写：

func ImportUsersBatch(r io.Reader, save func([]User) error) error {
	const batchSize = 500
	batch := make([]User, 0, batchSize)

	return ImportUsers(r, func(user User) error {
		batch = append(batch, user)
		if len(batch) < batchSize {
			return nil
		}

		if err := save(batch); err != nil {
			return err
		}
		batch = batch[:0]
		return nil
	})
}

上面代码还缺最后一批保存。可以稍微调整：

func ImportUsersBatch(r io.Reader, save func([]User) error) error {
	const batchSize = 500
	batch := make([]User, 0, batchSize)

	err := ImportUsers(r, func(user User) error {
		batch = append(batch, user)
		if len(batch) == batchSize {
			if err := save(batch); err != nil {
				return err
			}
			batch = batch[:0]
		}
		return nil
	})
	if err != nil {
		return err
	}
	if len(batch) > 0 {
		return save(batch)
	}
	return nil
}

这类结构很适合导入任务。

流式写出 JSON

如果要导出数据，也可以逐条编码：

func ExportUsers(w io.Writer, users []User) error {
	encoder := json.NewEncoder(w)

	if _, err := w.Write([]byte("[\n")); err != nil {
		return err
	}
	for i, user := range users {
		if i > 0 {
			if _, err := w.Write([]byte(",\n")); err != nil {
				return err
			}
		}
		if err := encoder.Encode(user); err != nil {
			return err
		}
	}
	if _, err := w.Write([]byte("]\n")); err != nil {
		return err
	}
	return nil
}

如果数据来自数据库分页，你可以一页页查询，一条条写到 HTTP 响应，避免把全部结果放进内存。导出接口还要注意超时、客户端断开和权限控制。

请求体大小仍然要限制

流式解码不等于可以接受无限输入。HTTP handler 里仍然应该限制大小：

r.Body = http.MaxBytesReader(w, r.Body, 20<<20) // 20 MB
defer r.Body.Close()

然后再把 r.Body 交给 Decoder。大文件导入最好有明确大小上限和异步处理流程，不要让一个 HTTP 请求无限跑。

错误行号和部分成功

导入类接口还会遇到一个产品问题：第 738 条数据失败时，前 737 条要不要保存？如果保存了，用户重新上传会不会重复？这些问题和 JSON 解码方式无关，但流式处理会让它们更早暴露。比较常见的做法是按批次校验，整批成功后再写入；或者给每条记录设计幂等键，让重复导入不会产生重复数据。

如果希望错误更友好，可以在循环里维护行号或序号：

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

这样用户看到的是“第 738 条邮箱为空”，而不是一段底层 JSON 错误。工程上也更容易排查，因为日志里有明确位置。流式处理不只是省内存，还要求你把错误处理、事务边界和幂等策略想清楚。

常见问题 FAQ

Q: Decoder 和 Unmarshal 性能差异大吗？
A: 小数据时差异很小。大数据时 Decoder 的流式优势在内存上，不是解码速度。如果追求极致 JSON 性能，可以考虑第三方库如 json-iterator 或 sonic。

Q: 流式解码能部分成功吗？
A: 取决于业务设计。可以按批次提交数据库，某条失败时前面已提交的不会回滚。或者全量读入内存再做整体校验后统一写入。根据业务选择。

Q: 未知字段怎么处理？
A: Decoder 逐元素读取时只解目标字段，未知字段默认被丢弃。如果需要检测未知字段，可以用 map[string]json.RawMessage 做中转。

常见陷阱

1. 读完后没有关闭文件/Reader：defer file.Close() 是基础习惯。
2. 数组嵌套结构解析错误：decoder.Token() 可以读取任意 token，遇到嵌套对象或数组时要用类型断言正确处理。
3. HTTP body 被反复读取：流式解码后 body 已耗尽，不要尝试再读一遍。需要备份时用 io.TeeReader。

对比表

小结

json.Decoder 可以从 io.Reader 流式读取 JSON，适合大数组、导入任务和 HTTP 请求体。你可以用 Token 和 More 逐个处理数组元素，边读边写数据库。导出时也可以用 json.Encoder 逐条写出。

流式处理能减少内存压力，但仍然要限制输入大小、处理错误、考虑超时。它不是复杂技巧，而是面对大数据时更稳的基本功。养成对导入接口限制请求体和记录处理进度的习惯，能避免很多线上故障。

真实项目用例

在实际团队协作中，下面是几个推荐的工作流：

代码审查清单

• 函数是否处理了所有 error 返回值
• 并发代码是否有明确的退出路径和 WaitGroup
• 用户输入是否经过校验和清洗
• 敏感配置是否通过环境变量或加密存储注入
• 测试是否覆盖了正常路径和至少一个错误路径
• 日志是否包含足够的上下文信息但不泄露敏感数据
• 接口设计是否符合最小接口原则

CI/CD 集成建议

• 每次提交前运行 go fmt ./...
• CI 中运行 go vet ./... 和 golangci-lint run
• 单元测试使用 go test -race ./... 检测数据竞争
• 关键路径的 benchmark 加入回归测试
• 使用 go mod verify 确保依赖完整性

性能调优检查点

• 使用 pprof 分析 CPU 和内存使用
• 关注 benchmark 的 allocs/op，减少高频路径的堆分配
• 检查数据库查询是否使用索引
• 确认外部 HTTP 调用有合理的超时设置
• 缓存热点数据，但注意缓存一致性和过期策略

面试高频考点

如果你正在准备 Go 相关面试，以下概念是高频考点：

1. goroutine 和线程的区别
2. channel 的缓冲和非缓冲用法
3. defer 的执行顺序和与返回值的关系
4. map 的并发不安全性和解决方案
5. interface 的隐式实现和类型断言
6. slice 的底层数组和 append 机制
7. GC 的基本原理和调优参数
8. context 的使用场景和超时控制
9. error 的包装和 errors.Is/errors.As
10. sync.Mutex vs sync.RWMutex vs atomic

掌握这些概念意味着你具备了独立开发 Go 服务的基础能力。继续在实际项目中磨练，你会越来越熟悉 Go 的工程风格和最佳实践。

常见问题（FAQ）

Q: 这个特性在实际项目中真的有用吗？
A: 是的。本文介绍的技术来源于真实后端开发场景。无论是标准库工具还是工程实践，在日常服务开发中都会反复用到。

Q: Go 版本会影响示例代码吗？
A: 本文代码主要针对 Go 1.20+ 编写。较新版本（如 1.22、1.23）的语法可能有微调，但核心概念保持不变。如有版本差异，文中会特别说明。

Q: 学习 Go 应该先学标准库还是直接上框架？
A: 强烈建议先学标准库。框架是对标准库的封装和扩展。只有理解了标准库的能力边界，才能正确选择和使用框架，也才能在框架出问题时快速定位。

Q: 代码里的错误处理为什么都是显式的 if err != nil？
A: 这是 Go 的设计哲学。显式错误处理让失败路径清晰可见，不会隐藏在任何 try-catch 之后。习惯了之后，你会发现这种写法实际上降低了排查错误的难度。

Q: 并发相关代码怎么测试？
A: 使用 Go 内置的 -race 标志检测数据竞争：go test -race ./...。结合 sync.WaitGroup 和 context.WithTimeout 编写有退出路径的并发测试，避免 goroutine 泄漏。

常见坑与避坑指南

1. 不要信任用户输入：无论表单、JSON、Cookie 还是 HTTP Header，都当作不可信数据处理，做校验和转义。
2. 资源要释放：文件、数据库连接、HTTP 响应体都要及时关闭。defer 是一个好习惯。
3. 不要忽略错误：即使 defer file.Close() 可能返回错误，至少记录日志。完全忽略错误是 bug 的温床。
4. 不要滥用 goroutine：每个 goroutine 都要有明确的退出路径。使用 sync.WaitGroup 和 context 管理生命周期。
5. 不要硬编码配置：端口、路径、超时时间、密钥都应该从配置读取，让程序适应不同环境。
6. 不要过早优化：先让代码正确和可读，再用 benchmark 和 profile 找到真正的热点。

延伸阅读与实践建议

读完本文后，建议完成以下实践：

1. 把文中所有示例代码在自己的机器上跑一遍
2. 给示例代码补充错误分支的测试用例
3. 尝试基于本文内容构建一个小型完整项目
4. 在 review 他人的 Go 代码时，检查本文提到的边界是否被覆盖
5. 订阅 Go 官方博客，关注语言演进和最佳实践更新

参考资源

• Go 官方网站：https://go.dev/
• Go 标准库文档：https://pkg.go.dev/std
• Go by Example：https://gobyexample.com/
• Effective Go：https://go.dev/doc/effective_go
• Go 常见问题：https://go.dev/doc/faq
• Go 项目实战社区案例和开源项目源码

本文力求在讲解技术细节的同时兼顾工程实用性。Go 语言的设计简洁但不简单，掌握它需要持续的实践和反思。希望这篇文章能成为你学习道路上的一个可靠参考。

NDJSON（行分隔 JSON）处理

对于日志流或实时数据推送，NDJSON 是更合适的格式：

{"id":1,"name":"a"}
{"id":2,"name":"b"}
{"id":3,"name":"c"}

每行是一个独立 JSON 对象，可以用 bufio.Scanner + json.Decoder 逐行解析：

scanner := bufio.NewScanner(r)
for scanner.Scan() {
    var item Item
    if err := json.Unmarshal(scanner.Bytes(), &item); err != nil {
        return err
    }
    if err := process(item); err != nil {
        return err
    }
}

NDJSON 的优势是不用维护数组括号，可以随意追加和截断，非常适合流式场景。

Decoder 的 Token 模式

对于不完全了解的 JSON 结构，用 Token 逐个读取：

dec := json.NewDecoder(r)
for {
    tok, err := dec.Token()
    if err == io.EOF {
        break
    }
    if err != nil {
        return err
    }
    switch t := tok.(type) {
    case json.Delim:
        fmt.Printf("delim: %v\n", t)
    case string:
        fmt.Printf("string: %s\n", t)
    case float64:
        fmt.Printf("number: %f\n", t)
    }
}

Token 模式可以处理任意 JSON 结构，不需要预定义模型。这在处理外部非结构化数据时很有用。

Decoder 的缓冲控制

json.Decoder 默认带有内部缓冲（默认 4KB）。对于大字符串字段，可能会多占内存：

dec := json.NewDecoder(r)
dec.UseNumber() // 数字解析为 json.Number 而非 float64，避免精度丢失

UseNumber 适合处理大整数（如订单 ID、用户 ID），因为 json.Number 保存原始字符串，不会丢失精度。

对比：流式 vs 全量

选择依据是数据量而非喜好。数据 < 1MB 时两者差异不明显，> 100MB 时必须用 Decoder。

最终建议

处理大 JSON 数据时要特别注意：不仅要节省内存，还要让程序能够优雅地处理格式错误。流式解析的好处之一就是可以逐条验证，发现单条格式错误时不至于导致整个解析失败。这在导入业务中尤为重要：几百条数据中一条出错，不应该让其他正常数据也无法入库。

错误恢复的流式解析

流式解析的另一个优势是容错。如果 JSON 数组中有几条格式异常，可以跳过而不是全量失败：

for dec.More() {
    var item ImportItem
    if err := dec.Decode(&item); err != nil {
        log.Printf("item %d decode error: %v", itemNum, err)
        // 尝试跳过这个元素
        if err := skipValue(dec); err != nil {
            return err
        }
        continue
    }
    if err := save(item); err != nil {
        return fmt.Errorf("save item %d: %w", itemNum, err)
    }
    itemNum++
}

这种容错模式在导入第三方数据时非常实用，不能因为一条脏数据就全盘失败。当然，容错策略要根据业务需求设计，不能一味跳过所有错误。

掌握流式 JSON 处理后，面对大文件、实时流、不规范数据都会更有信心。这是从"能用 JSON"到"用好 JSON"的关键一步。