json.Encoder能流式返回是因为它直接写入io.Writer边编码边发送，不缓存全量数据；而json.Marshal必须将整个结构序列化为[]byte后才返回，导致大数组易OOM或超时。
为什么 json.Encoder 能流式返回，而 json.Marshal 不能
因为 json.Marshal 必须把整个数据结构序列化成 []byte 才能返回，内存里存着完整 JSON 字符串；json.Encoder 直接写入 io.Writer（比如 HTTP 响应体），边编码边发，不攒全量。适合大数组、实时日志、长连接推送等场景。
常见错误现象：json.Marshal 处理几万条记录时 OOM 或响应超时；用 fmt.Fprintf(w, "%s", jsonStr) 拼接多段 JSON 导致格式非法（缺逗号、括号不闭合）。
- 必须设置
Content-Type: application/json，否则前端可能不解析流式内容 - HTTP/1.1 下需禁用缓存：
w.Header().Set("Cache-Control", "no-cache") - 不要调用
w.WriteHeader()太早——json.Encoder第一次写入时会自动触发状态码发送，提前写可能冲突
用 json.Encoder 返回数组流的正确姿势
典型需求：查数据库分页游标扫描，逐条 encode 并 flush。不能先 collect 到 slice 再 encode，那就失去流式意义了。
关键点是手动控制 JSON 数组结构：开头写 [，每条数据后写 ,（除最后一条），结尾写 ]。但更稳妥的做法是用换行分隔（NDJSON），避免语法校验和客户端解析负担。
立即学习“go语言免费学习笔记（深入）”；
- 推荐 NDJSON（每行一个合法 JSON 对象）：
encoder.Encode(item)每次调用都输出完整对象 + 换行，无需手动拼括号和逗号 - 若坚持标准 JSON 数组，需手动写
[和]，并在首次写后记录是否已写过元素，控制逗号逻辑 - 每次
encoder.Encode()后建议w.(http.Flusher).Flush()（确认w支持），否则底层缓冲可能滞留
encoder := json.NewEncoder(w)
w.Header().Set("Content-Type", "application/x-ndjson")
for rows.Next() {
var item MyStruct
if err := rows.Scan(&item); err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
encoder.Encode(item) // 自动加换行
if f, ok := w.(http.Flusher); ok {
f.Flush()
}
}
json.Encoder 在 HTTP 长连接中容易卡住的几个原因
不是代码写错了，而是网络层或客户端行为导致“看起来没数据”。最常被忽略的是 TCP 缓冲和 HTTP 分块编码交互问题。
- Go 的
http.Server默认启用 HTTP/1.1 分块传输（chunked），但某些反向代理（如 Nginx 默认配置）会缓冲第一个 chunk，直到收到 EOF 或缓冲满才转发 —— 这就造成“前端收不到首条数据” - 客户端（尤其是浏览器 fetch）对流式 JSON 支持有限：不支持标准 JSON 数组流，只认 NDJSON 或自定义分隔符；且需设置
responseType: 'text'+ 手动按行解析 - 如果 handler 中有 panic 或未捕获 error，
json.Encoder可能已写部分字节，但连接被断开，客户端收到截断 JSON
兼容性与性能要注意的边界情况
json.Encoder 本身很轻量，但实际吞吐受制于三处：序列化耗时、I/O 写入速度、客户端消费能力。别假设“用了流式就一定快”。
- 结构体字段太多或嵌套深时，
json.Encoder序列化开销仍存在，可考虑预计算字段或用ffjson/easyjson替代（但会牺牲可维护性） - 并发写同一个
json.Encoder实例会 panic —— 每个请求必须新建json.Encoder，它不保证并发安全 - Go 1.21+ 支持
json.Encoder.SetEscapeHTML(false)关闭 HTML 转义，减少小字符串开销；旧版本只能靠自定义 marshaler
真正难的从来不是怎么调用 json.Encoder.Encode()，而是判断该不该流、谁来负责断连重试、怎么让前端稳定解析每一行。这些不在函数签名里，但在生产环境天天出问题。
