Go encoding/json/v2 怎样把大对象流式编码到 Writer

当一个接口要返回大对象时，先把整个结果交给 json.Marshal 再写入响应，通常会多出一份连续的 []byte。Go 1.27 的 encoding/json/v2 提供了 MarshalWrite，可以直接把 JSON 编码到 io.Writer；如果还需要控制 token 或语法层，再使用 encoding/json/jsontext 的 Encoder。

官方地址：https://pkg.go.dev/encoding/json/v2

实用选择是：普通结构体输出优先用 json.MarshalWrite，把 HTTP 响应、文件或压缩流作为 Writer；需要手动写对象边界、逐个写 token 或读取输出偏移时，才下沉到 jsontext.Encoder。流式编码减少的是中间完整字节切片，不代表对象本身、嵌套字符串或 Writer 缓冲区都不占内存。

先分清三种 JSON 输出入口

encoding/json/v2 的 API 可以按输出控制粒度分成三层：Marshal 返回完整字节切片；MarshalWrite 负责语义编码并写入 io.Writer；jsontext.Encoder 负责更底层的 token/value 语法流。它们都属于 JSON 编码，但承担的边界不同。

因此，“大对象”不是自动切换底层 API 的理由。先看调用点是否只需要把一个 Go 值编码出去；如果是，优先用高层的 MarshalWrite，让包负责值到 JSON 的语义映射。只有当输出本身需要逐项组合，才进入 jsontext。

用 MarshalWrite 把对象直接编码到 Writer

普通大对象输出可以把目标抽象成 io.Writer，调用 json.MarshalWrite。下面的函数同时适用于文件、响应缓冲区和其他实现了 Writer 的输出目标；它不先创建一份完整 JSON 字节切片。

package main

import (
    "fmt"
    "io"

    json "encoding/json/v2"
)

type Report struct {
    ID      string   `json:"id"`
    Summary string   `json:"summary"`
    Items   []string `json:"items"`
}

func writeReport(w io.Writer, report Report) error {
    // 直接把语义编码结果写给目标 Writer，避免先组装完整 []byte。
    if err := json.MarshalWrite(w, report); err != nil {
        return fmt.Errorf("write report json: %w", err)
    }
    return nil
}

这里的关键点是错误必须向上返回。编码过程可能因为值不支持 JSON 语义而失败，也可能因为 Writer 已经关闭、磁盘写入失败或客户端断开而失败；调用方不应该把这些错误都当成成功响应。

如果输出是 HTTP 响应，响应头和状态码应在写入正文前决定。若 Writer 只写出了一部分内容后失败，不能假设还能把一个新的 JSON 错误对象追加到同一个响应中；更稳妥的做法是记录结构化日志，并让上层根据响应是否已经开始写出决定关闭连接或采用协议级错误。

需要 token 控制时使用 jsontext.Encoder

当一个 JSON 文档由多个来源拼成，或者你需要显式写对象开始、字段名、字段值和对象结束时，可以直接创建 jsontext.Encoder。它处理的是 JSON 语法 token 和 value，不再替你推断完整业务对象的字段结构。

package main

import (
    "fmt"
    "io"

    "encoding/json/jsontext"
)

func writeEnvelope(w io.Writer, name string, count int) error {
    enc := jsontext.NewEncoder(w)

    // 显式写边界，便于在同一份文档中组合不同来源的字段。
    if err := enc.WriteToken(jsontext.BeginObject); err != nil {
        return fmt.Errorf("begin object: %w", err)
    }
    if err := enc.WriteToken(jsontext.String("name")); err != nil {
        return fmt.Errorf("write name key: %w", err)
    }
    if err := enc.WriteToken(jsontext.String(name)); err != nil {
        return fmt.Errorf("write name value: %w", err)
    }
    if err := enc.WriteToken(jsontext.String("count")); err != nil {
        return fmt.Errorf("write count key: %w", err)
    }
    if err := enc.WriteToken(jsontext.Int(count)); err != nil {
        return fmt.Errorf("write count value: %w", err)
    }
    // 关闭对象，保证输出仍然满足 JSON 的结构边界。
    if err := enc.WriteToken(jsontext.EndObject); err != nil {
        return fmt.Errorf("end object: %w", err)
    }
    return nil
}

token 级接口的代价是责任更多：字段名和值必须交替出现，对象和数组的开始、结束必须匹配，底层 Writer 的失败也会从写 token 的调用点返回。若只是把一个已定义的结构体写出去，手动管理这些边界反而增加出错面。

错误和内存边界要怎样判断

流式编码最容易被误解成“完全不占内存”。更准确的说法是：它不要求调用方先保留完整 JSON 字节结果，但待编码的 Go 对象、字符串字段、切片、编码器内部状态和 Writer 的缓冲仍然会占用内存。

• 对象本身很大：优先把查询或读取结果拆成可控批次，再分别写入协议允许的数组或对象结构；仅把 Marshal 换成 MarshalWrite 不会把一个已经加载的巨型切片变成流。
• Writer 失败：保留原始错误链，用 %w 包装；不要在正文已经写出后再追加一个看似完整的错误 JSON。
• 语法失败：token 级写入通常在当前调用点报告错误；需要更细的定位时，可以结合 Encoder.OutputOffset 和错误类型记录输出位置。
• 需要格式化：使用 jsontext 的选项表达缩进、空格或转义策略，不要在 JSON 写出后再用字符串替换修改结构。

在 HTTP 场景，还要区分“编码成功”与“客户端完整收到”。Writer 返回成功只代表当前写入路径接受了数据；传输层、代理和客户端是否完整接收，属于更外层的协议与连接问题。

按输出目标选择 API

落地时建议把 Writer 作为函数参数，把错误处理留在边界函数中，并在日志中记录输出目标类型、对象批次和失败位置。这样既能替换文件、HTTP 或压缩 Writer，也不会把 JSON 编码策略散落到业务层。

MarshalWrite 会不会自动把切片逐项从数据库读出来？

不会。它只负责把传入的 Go 值写成 JSON。数据库游标、分页读取或分块协议需要调用方设计，不能由一个编码函数推断。

什么时候不应该使用 jsontext.Encoder？

如果目标只是编码一个稳定的结构体，优先使用 MarshalWrite。只有在需要 token、value、格式选项或输出偏移等语法层能力时，才使用 jsontext.Encoder。

Writer 写失败后还能继续写 JSON 吗？

通常不应继续把它当成一份完整文档。先保留错误链并停止当前输出；如果是 HTTP 响应，还要根据响应是否已经提交选择关闭连接或交给上层协议处理。

小结：Go 1.27 的 encoding/json/v2 已经把“编码到 Writer”作为明确入口。普通值用 MarshalWrite，token 级组合用 jsontext.Encoder，两者都要认真处理 Writer 错误；真正的大对象治理则要继续控制对象生命周期和批次大小。