golang

Go JSON 流式响应入门：边查边写，避免一次性占满内存

很多列表接口一开始会把所有数据查出来，放进切片，再 。数据少时没问题，数据一多，内存会飙升，用户也要等全部数据准备好才能收到响应。对于导出类接口，可以考虑流式 JSON 响应：边查、边编码、边写给客户端。

PlumePHP 11 分钟阅读 5366 字

很多列表接口一开始会把所有数据查出来，放进切片，再 json.NewEncoder(w).Encode(slice)。数据少时没问题，数据一多，内存会飙升，用户也要等全部数据准备好才能收到响应。对于导出类接口，可以考虑流式 JSON 响应：边查、边编码、边写给客户端。

本文用导出用户列表做例子。目标不是让每个 API 都流式化，而是理解 json.Encoder、http.Flusher、客户端断开和错误边界。

最简单的数组流式输出

func StreamUsers(w http.ResponseWriter, r *http.Request, users <-chan User) error {
	w.Header().Set("Content-Type", "application/json; charset=utf-8")
	enc := json.NewEncoder(w)

	if _, err := w.Write([]byte("[\n")); err != nil {
		return err
	}
	first := true
	for user := range users {
		if !first {
			if _, err := w.Write([]byte(",\n")); err != nil {
				return err
			}
		}
		first = false
		if err := enc.Encode(user); err != nil {
			return err
		}
	}
	if _, err := w.Write([]byte("]\n")); err != nil {
		return err
	}
	return nil
}

这里手写了数组的 [、,、]，每个用户用 Encoder.Encode 写出。Encode 会在每个对象后加换行，这对 JSON 数组是可以接受的。

配合分页查询

真实数据通常来自数据库分页：

func StreamUsersFromStore(ctx context.Context, w http.ResponseWriter, store Store) error {
	w.Header().Set("Content-Type", "application/json; charset=utf-8")
	enc := json.NewEncoder(w)
	w.Write([]byte("["))
	first := true

	var afterID int64
	for {
		users, err := store.ListUsers(ctx, afterID, 500)
		if err != nil {
			return err
		}
		if len(users) == 0 {
			break
		}
		for _, user := range users {
			if !first {
				w.Write([]byte(","))
			}
			first = false
			if err := enc.Encode(user); err != nil {
				return err
			}
			afterID = user.ID
		}
	}
	w.Write([]byte("]"))
	return nil
}

这避免一次性把所有用户读进内存。分页大小要结合数据库和响应速度调整，500 或 1000 都只是示例。

Flush 让客户端更早收到

如果希望客户端更早看到数据，可以使用 http.Flusher：

if flusher, ok := w.(http.Flusher); ok {
	flusher.Flush()
}

可以每写一页 flush 一次。不要每条都 flush，太频繁会增加网络开销。反向代理也可能缓冲响应，所以 flush 不一定保证客户端马上看到，但它能表达服务端愿意推送。

错误边界很难

流式响应有一个现实问题：一旦你已经写出 [ 和部分数据，状态码就基本定了。后面数据库出错时，不能再返回标准 JSON 错误响应。客户端可能拿到一个不完整 JSON。

所以流式响应更适合导出和内部数据拉取，不适合普通业务接口。普通接口通常应该先完成业务处理，再返回完整 JSON。流式化是为了解决大数据输出，不是默认写法。

一种替代方案是 NDJSON，每行一个 JSON 对象：

for _, user := range users {
	if err := enc.Encode(user); err != nil {
		return err
	}
}

NDJSON 不需要数组闭合，部分失败时客户端至少能处理已经收到的完整行。但客户端必须支持这种格式。

客户端断开

写响应时如果客户端断开，Write 或 Encode 会返回错误。查询数据库时也应该使用 r.Context()：

func handler(w http.ResponseWriter, r *http.Request) {
	if err := StreamUsersFromStore(r.Context(), w, store); err != nil {
		log.Printf("stream users: %v", err)
	}
}

用户取消下载后，context 会取消，数据库查询和循环应该尽快停止。不要在流式接口里用 context.Background()。

测试响应格式

func TestStreamUsers(t *testing.T) {
	users := make(chan User, 2)
	users <- User{ID: 1, Name: "A"}
	users <- User{ID: 2, Name: "B"}
	close(users)

	rec := httptest.NewRecorder()
	err := StreamUsers(rec, httptest.NewRequest(http.MethodGet, "/", nil), users)
	if err != nil {
		t.Fatal(err)
	}
	var got []User
	if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
		t.Fatal(err)
	}
	if len(got) != 2 {
		t.Fatalf("len = %d", len(got))
	}
}

测试时不要只看字符串包含，最好反解析 JSON，确认输出结构合法。

响应头和缓存

流式接口的响应头要尽早写清楚。普通 JSON 可以先拼完再决定状态码，但流式响应一旦写出第一段内容，状态码通常就不能改了。因此校验参数、检查权限、确认游标是否合法，都应该在第一次 Encode 之前完成。

func streamLogs(w http.ResponseWriter, r *http.Request) {
	if r.URL.Query().Get("token") == "" {
		http.Error(w, "missing token", http.StatusUnauthorized)
		return
	}

	w.Header().Set("Content-Type", "application/x-ndjson")
	w.Header().Set("Cache-Control", "no-store")

	enc := json.NewEncoder(w)
	_ = enc.Encode(map[string]string{"level": "info", "msg": "started"})
}

Cache-Control: no-store 不是必须，但日志、导出进度、任务事件这类接口一般不希望被中间层缓存。若公司有网关或 CDN，最好和运维确认它们是否会缓冲响应。某些代理为了优化吞吐，会等缓冲区达到一定大小再发给客户端，这会让“实时流”看起来像卡住。

和 gzip 的关系

流式 JSON 可以配合 gzip，但要小心刷新。gzip 会自己维护压缩缓冲，如果中间件只在请求结束时关闭 writer，客户端可能很久看不到数据。简单做法是：对真正要求实时的接口先关闭 gzip，确认链路稳定后再优化。

如果一定要压缩，可以让中间件支持 Flush，并在每条记录后同时刷新 gzip writer 和 HTTP writer。入门阶段不要把这个复杂度塞进业务 handler，先把协议和错误处理写清楚更重要。

服务端日志

流式接口的失败经常发生在响应中途，比如客户端关闭浏览器、网络断开、下载工具超时。此时 Encode 可能返回 broken pipe 或上下文取消。日志级别不要一律记成 error，否则线上会被正常断连刷屏。

if err := enc.Encode(row); err != nil {
	if errors.Is(r.Context().Err(), context.Canceled) {
		log.Printf("client canceled stream")
		return
	}
	log.Printf("write stream row: %v", err)
	return
}

判断是否为客户端取消，可以先看 r.Context().Err()。真正需要报警的是数据库持续失败、生成数据异常、权限绕过等服务端问题，而不是用户关掉页面。

小结

Go 可以用 json.Encoder 和 io.Writer 流式写 JSON 响应，适合大列表导出和边查边写场景。结合分页查询可以减少内存占用，结合 http.Flusher 可以让客户端更早收到数据。

流式响应的错误边界更复杂：写出部分内容后，很难再返回统一错误 JSON。普通业务接口不要盲目流式化。只有当数据量和等待时间确实成为问题时，再使用这种模式。

常见问题与解答

流式响应能大幅减少内存吗？

如果数据量很大（万条以上），是的。流式响应边走边写，不需要把所有数据加载到内存再编码。但如果数据只有几十条，普通 json.Marshal 更简单，不会有明显内存问题。

客户端收到不完整 JSON 怎么办？

这是流式响应的主要缺点。一旦开始发送，出错后无法返回标准错误 JSON。可以：

  1. 用 NDJSON（每行一个 JSON 对象），最后不闭合数组
  2. 先计算或验证数据，确认无错后再开始流式发送
  3. 客户端处理不完整的响应，丢弃已收到的部分

和 HTTP/2 的关系

HTTP/2 的多路复用让多个流式请求更友好，不会因为一个慢流阻塞其他请求。但单个流本身的流式逻辑没有变化。

流式 CSV 导出

除了 JSON，CSV 也适合流式输出：

func exportCSV(w http.ResponseWriter, r *http.Request, rows <-chan []string) {
    w.Header().Set("Content-Type", "text/csv")
    w.Header().Set("Content-Disposition", "attachment; filename=export.csv")

    writer := csv.NewWriter(w)
    defer writer.Flush()

    writer.Write([]string{"ID", "Name", "Email"})

    for row := range rows {
        if err := writer.Write(row); err != nil {
            log.Printf("csv write: %v", err)
            return
        }
        writer.Flush()
        if f, ok := w.(http.Flusher); ok {
            f.Flush()
        }
    }
}

Content-Disposition 告诉浏览器这是下载，不是页面展示。这是导出功能的标准做法。

流式响应的错误日志

流式接口的错误通常发生在响应中途：

if err := enc.Encode(item); err != nil {
    if ctxErr := r.Context().Err(); ctxErr != nil {
        log.Printf("client disconnected during stream: %v", ctxErr)
        return
    }
    log.Printf("stream encode error: %v", err)
    return
}

区分客户端断开和服务端错误，避免把正常断连记成 error。

实践练习

完成以下练习以巩固所学知识：

  1. 阅读 Go 官方文档相关章节
  2. 编写一个完整的示例程序
  3. 为示例程序编写单元测试
  4. 使用 go test 和 go benchmark 验证实现
  5. 尝试优化内存分配和运行时间

推荐阅读

真实项目用例

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

代码审查清单

  • 函数是否处理了所有 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 语言的设计简洁但不简单，掌握它需要持续的实践和反思。希望这篇文章能成为你学习道路上的一个可靠参考。

真实项目应用场景

在企业级后端开发中，本技术点通常出现在以下场景：

场景一：服务初始化

在生产环境的服务启动过程中，正确初始化配置、日志、数据库连接和健康检查端点是基本要求。任何一个环节的疏忽都可能导致发布失败或线上故障。

场景二：请求处理链

每个 HTTP 请求都会经历认证、限流、日志记录、业务处理、响应构造等多个阶段。理解每个阶段的职责边界，能帮助你在出现问题时快速定位。

场景三：数据持久化

无论是关系型数据库还是缓存存储，数据的读写一致性、连接池管理和错误处理都需要精心设计。测试替身（stub/mock）是确保数据访问层可测的关键。

场景四：异步任务处理

后台任务如数据同步、报表生成、邮件发送等通常采用异步方式处理。worker 池、任务队列和重试机制是不可或缺的组成部分。

场景五：可观测性建设

日志、指标和追踪是系统的"体检报告"。结构化日志便于检索，关键指标帮助发现趋势，分布式追踪定位跨服务问题。

性能考量

在代码层面，有几个通用的性能原则：

  1. 减少不必要的分配：频繁的小对象分配会增加 GC 压力。使用 sync.Pool 复用缓冲区，预分配切片容量。
  2. 避免反射：反射带来的性能开销在热路径上不可忽视。尽量在编译期确定类型。
  3. 批量操作优于逐条操作：数据库批量插入、Redis pipeline、HTTP 批量请求都能显著减少网络往返。
  4. 懒加载：不是每个请求都需要加载全部数据。按需加载，配合缓存减少重复计算。
  5. 合理超时：网络请求一定要设超时。没有超时的外部调用是隐形炸弹。

安全红线

  • 永远不要信任用户输入，做严格的输入校验和输出转义
  • 敏感信息（密码、密钥、Token）不要硬编码，不要进入日志
  • SQL 查询使用参数化查询，禁止字符串拼接
  • 使用 crypto/rand 生成安全随机数，不要用 math/rand
  • Cookie 设置 HttpOnly、Secure 和合适的 SameSite
  • 生产环境关闭调试接口和详细错误堆栈回显

团队协作约定

统一的代码风格和工程约定能大幅降低维护成本：

  • 包名：简短、有意义，避免 utils、common、helper
  • 接口：由使用方定义，保持小而精
  • 错误：底层包装上下文，上层边界统一记录，不重复打印
  • 测试：核心逻辑必须有测试覆盖，表驱动 + 子测试是推荐方式
  • 文档：公共 API 和关键设计要有注释，复杂业务逻辑要说明为什么
  • 提交信息：说明做了什么和为什么，便于后续回溯

调试技巧

当程序行为不符合预期时：

  1. 先确认输入数据是什么，不是你以为的什么
  2. 用 go test -race 检查是否存在数据竞争
  3. 用 go tool pprof 分析 CPU 和内存热点
  4. 增加结构化日志，打印关键路径的输入输出
  5. 在本地用最小复现案例定位问题，不要在线上试错
  6. 检查环境差异：Go 版本、操作系统、时区、环境变量

持续学习路径

掌握基础后，可以继续深入以下方向：

  • Go 运行时：调度器（GMP 模型）、GC 算法、内存分配
  • 网络编程：TCP/UDP、QUIC、gRPC、WebSocket
  • 系统编程：Linux syscall、BPF、eBPF
  • 云原生：Kubernetes operator、服务网格、可观测性
  • 编译原理：Go 编译器、SSA、逃逸分析

总结

Go 语言的魅力在于简洁与务实之间的平衡。它没有花哨的语法糖，但每一行代码都在为工程可靠性服务。标准库涵盖了大多数日常需求，让你可以用少量依赖构建稳定的系统。

本文介绍的技术点虽然聚焦在入门的某一方面，但它们共同构成了一张可靠后端服务的安全网：从输入校验到错误处理，从资源管理到并发控制，从测试覆盖到可观测性。这些基本功练扎实了，后面学习框架、微服务和云原生都会事半功倍。

希望这篇教程能帮助你写出更清晰、更可靠、更容易维护的 Go 代码。

本文内容力求准确，但技术细节可能随 Go 版本更新而变化。建议以官方文档为准，并在实际项目中验证所有代码示例。

继续阅读

探索更多技术文章

浏览归档，发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「golang」更多文章

  1. 熔断、降级与限流：Go 微服务韧性设计完全指南
  2. 事件溯源与 CQRS 在 Go 中的实践：复杂业务系统的架构升级
  3. TinyGo 嵌入式开发与物联网实战：微控制器编程完全指南