json.NewEncoder比手动拼接更可靠，因其流式编码、自动错误传播、避免OOM和响应截断，且天然适配HTTP响应等io.Writer场景，而手动拼接易漏转义、错结构、丢字段。
json.NewEncoder 为什么比手动拼接更可靠
直接用 json.NewEncoder 写流式 JSON，核心优势不是“快”，而是“不崩”。手动拼 JSON 字符串容易漏转义、错结构、丢字段，尤其当数据含中文、换行、null 或嵌套 map/slice 时，json.Marshal 后再写入还可能因中间内存分配导致 OOM。而 json.NewEncoder 是边序列化边写，底层用 io.Writer 接口，天然适配文件、HTTP 响应、管道等场景。
常见错误现象：panic: json: unsupported type: map[interface {}]interface{} —— 这通常是因为传了非标准 map（比如 key 是 interface{} 而非 string），json.NewEncoder 同样会报，但至少不会写出非法 JSON。
- 必须确保输入数据是 Go 原生可序列化类型（
map[string]interface{}、struct、slice 等） - 避免在循环中反复创建
json.NewEncoder实例——它本身轻量，但频繁 new + flush 可能触发不必要的 buffer 分配 - 若写入 HTTP 响应，务必提前设置
Content-Type: application/json，否则浏览器可能乱码或下载文件
如何用 json.NewEncoder 写多条独立 JSON 对象（NDJSON 场景）
日志、API 流式响应、CLI 输出常需每行一个 JSON 对象（即 NDJSON 格式）。json.NewEncoder 默认不换行，也不加逗号分隔，得自己控制。
关键点：每次调用 Encode() 会自动追加换行符，且内部已处理好对象间分隔。不用手写
，更不能用 fmt.Fprintln 混用。
立即学习“go语言免费学习笔记（深入）”；
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
enc := json.NewEncoder(w)
for _, item := range items {
if err := enc.Encode(item); err != nil {
// 处理单条失败，不影响后续
log.Printf("encode failed: %v", err)
continue
}
}
-
enc.Encode()自动加w.Write([]byte(" "))，否则会出现空行 - 如果需要自定义分隔符（如两个对象间加逗号），
json.NewEncoder不支持，得换json.Marshal+ 手动写，但失去流式优势 - 注意：
Encode()是阻塞调用，若w是慢速 writer（如网络连接），会卡住当前 goroutine
json.NewEncoder 的性能和缓冲控制要点
json.NewEncoder 底层用了 bufio.Writer 包装传入的 io.Writer，默认 buffer 大小是 4096 字节。对小对象高频写入，buffer 太大会延迟落盘；对大对象，太小会频繁 flush。
常见问题：Write() timeout 或 broken pipe 错误，往往不是编码问题，而是 writer 缓冲未及时刷新，下游已断开。
- 写完后建议显式调用
w.(io.Closer).Close()或bufw.Flush()（如果w是bufio.Writer） - 若写入文件，用
os.File直接传给json.NewEncoder即可，它内部会做 buffer；但若写入net.Conn，建议包一层bufio.Writer并设合理 size（如 8192） - 不要为追求极致性能关闭 buffer（如传
bytes.Buffer），除非你确定每次Encode()都很小且数量极少
遇到 invalid character ‘\’ looking for beginning of value 怎么办
这个错误几乎总是出现在：你本想用 json.NewEncoder 写 JSON，却在它之前或之后，用其他方式往同一个 io.Writer 写了非 JSON 内容（比如调试日志、HTTP header、HTML 片段）。
典型场景：HTTP handler 中先 w.Write([]byte("{" ))，再用 json.NewEncoder(w).Encode(...) —— 导致开头出现非法字符 {，破坏 JSON 结构。
- 确认整个输出流只由
json.NewEncoder控制，不要混用fmt.Fprintf、w.Write等 - 若需前置内容（如 SSE 的
data:前缀），就不能用json.NewEncoder，得改用json.Marshal+ 手动写 - 调试时用
bytes.Buffer接收输出，再string(buf.Bytes())查看原始字节，比猜更容易定位非法字符位置
流式 JSON 的难点不在编码逻辑，而在 writer 生命周期管理和输出契约的严格性——只要写入目标被多个地方共用，就极易出错。
