Go json/v2 MarshalWrite 怎样在把 JSON 写入 Writer（输入边界）

当你需要把一个 Go 值直接写进响应、文件或缓冲区时，encoding/json/v2 的 MarshalWrite 比先得到 []byte 再手动写出更贴合目标。它的调用边界很明确：第一个参数是实现了 io.Writer 的输出端，第二个参数才是要序列化的 Go 值，后面可以传入编码选项。函数不会自动追加换行；发生错误时，输出端可能已经收到部分内容。

官方文档：https://pkg.go.dev/encoding/json/v2

记住“Writer 在前、值在后”即可避免大多数误用；如果 HTTP 响应必须在编码成功后一次性提交，就先写入缓冲区，再把缓冲区交给响应端。

先分清 MarshalWrite 的输入输出契约

MarshalWrite(out, in, opts...) 把 in 按 JSON 语义编码到 out。out 可以是 bytes.Buffer、文件或 http.ResponseWriter；它不是 JSON 输入。opts 只影响本次序列化和编码，不是反序列化配置。

// 用缓冲区承接 JSON，便于在写入真正的输出端前统一处理错误。
package main

import (
    "bytes"
    jsonv2 "encoding/json/v2"
    "io"
)

type Report struct {
    Name  string `json:"name"`
    Count int    `json:"count"`
}

func writeReport(dst io.Writer, report Report) error {
    var buf bytes.Buffer
    // Deterministic 只控制可重复的序列化结果，不改变 Writer 的类型。
    if err := jsonv2.MarshalWrite(&buf, report, jsonv2.Deterministic(true)); err != nil {
        return err
    }
    // 编码成功后再把完整缓冲区交给调用方提供的 Writer。
    _, err := io.Copy(dst, &buf)
    return err
}

这段代码的重点不是“必须使用缓冲区”，而是把三个角色分开：report 是输入值，MarshalWrite 是编码函数，dst 是最终输出端。若你不需要在提交前拦截编码错误，也可以直接把 dst 作为第一个参数。

Writer 在前，JSON 值在后

最常见的错误是把参数顺序写成 MarshalWrite(value, writer)，或者误以为它会从 Writer 读取 JSON。对于 HTTP 处理器，http.ResponseWriter 正好满足 io.Writer，因此可以直接作为第一个参数。

// 直接把响应对象编码到 HTTP 响应端；示例只展示参数边界。
import (
    jsonv2 "encoding/json/v2"
    "net/http"
)

func writeHTTP(w http.ResponseWriter, report Report) {
    w.Header().Set("Content-Type", "application/json")
    // report 是待编码的 Go 值，w 才是接收 JSON 字节的 Writer。
    if err := jsonv2.MarshalWrite(w, report); err != nil {
        // 编码过程中可能已经写出部分内容，不能把这里当成可回滚事务。
        http.Error(w, "encode response failed", http.StatusInternalServerError)
    }
}

如果错误处理必须返回另一种完整响应，使用上一节的 bytes.Buffer 方案更稳妥；代价是需要先暂存编码结果。直接写入适合输出端本身就是流式目标、且调用方能接受写出后错误的场景。无论选择哪种方式，MarshalWrite 都不会为 JSON 自动补一个换行符。

三个输入边界要先确认

第一，确认版本和导入路径。Go 1.27 将 encoding/json/v2 作为新的 JSON API 提供，项目的工具链和模块语言版本要与这条导入路径匹配；不能把 v1 的 encoding/json.Encoder 方法名和 v2 的函数签名混写。

第二，确认选项属于编码方向。MarshalWrite 接收 marshal 或 encode 相关选项，例如 Deterministic(true)。反序列化选项不会因为也放进可变参数就自动生效，调用点应只保留与输出语义有关的配置。

第三，确认输出失败的处理方式。文件、网络响应和自定义 Writer 都可能在写出阶段返回错误。直接写出时，错误只说明这次编码或写入没有完整完成，不等于之前已经写出的字节会被撤回；需要可回滚的响应就采用“先缓冲、后提交”。

直接写出还是先缓冲：按结果要求选择

排查时可以按这条顺序看：先看第一个实参是否实现 io.Writer，再看第二个实参是否是要输出的 Go 值，最后检查选项是否属于 marshal/encode 方向。这样能把“参数顺序错误”“选项不生效”和“Writer 已写出后报错”分成三个独立问题。

常见问题

MarshalWrite 会自动换行吗？不会。需要换行时由调用方在 JSON 写出后单独写入换行字节，不能把换行当成 MarshalWrite 的默认行为。

为什么不总是直接写入 http.ResponseWriter？直接写出更省去中间缓冲，但一旦编码或底层写入失败，响应可能已有部分内容。对必须返回统一错误体的接口，先缓冲更容易控制结果。

资料依据：Go 1.27 发布说明 https://go.dev/doc/go1.27；json/v2 包文档 https://pkg.go.dev/encoding/json/v2。具体项目仍应以自身工具链和 Writer 实现的错误语义为准。