Go json/v2 MarshalWrite 怎样让 JSON 输出保持稳定顺序

如果 JSON 要参与签名、快照比较、缓存键生成或重复写入，同一份 Go 数据每次得到的字节都应该尽量一致。encoding/json/v2 中，MarshalWrite 负责把 JSON 写入 io.Writer，而 json.Deterministic(true) 负责要求同一输入得到稳定的序列化结果。

最小写法是把稳定性选项作为 MarshalWrite 的可变参数传入。它不是“把 Writer 变成有序容器”，也不会替调用方解决自定义序列化器里的随机性；它只改变 JSON 编码阶段的确定性语义。

MarshalWrite 与稳定输出分别负责什么

MarshalWrite(out, in, opts...) 有三个清晰的角色：目标 io.Writer、待编码的 Go 值，以及影响编码语义的选项。需要稳定字节时，直接加入 json.Deterministic(true)：

package main

import (
    "bytes"
    "fmt"
    "io"

    jsonv2 "encoding/json/v2"
)

type Envelope struct {
    ID      string         `json:"id"`
    Tags    []string       `json:"tags"`
    Payload map[string]any `json:"payload"`
}

func main() {
    value := Envelope{
        ID: "job-17",
        Tags: []string{"go", "json"},
        Payload: map[string]any{"z": 3, "a": 1},
    }

    var buf bytes.Buffer
    err := jsonv2.MarshalWrite(&buf, value, jsonv2.Deterministic(true))
    if err != nil {
        panic(err) // 写出失败时立即停止，避免把不完整 JSON 当成成功结果。
    }
    fmt.Println(buf.String()) // 说明图关注稳定字节，不把输出当成网络验证结果。
    _ = io.Discard // 示例只展示 Writer 形态，不额外引入运行时资源。
}

这里的重点是选项的位置：Deterministic(true) 与数据一起交给编码器，bytes.Buffer 只是示例 Writer。换成文件、响应体或自定义 Writer 时，稳定性选项的含义不变，但 Writer 自身的错误仍必须处理。

Deterministic 怎样影响 map 和结构体

官方文档对 Deterministic 的定义是：同一输入值应始终序列化为相同的输出字节；对原生 Go 类型，map 会按键排序。这个能力适合生成快照或签名输入，但“稳定”不等于“所有键都按业务顺序排列”。map 的稳定顺序来自编码规则，不是插入顺序。

结构体则要看字段的 JSON 表示和类型定义；不要把 map 的键排序规则误套到自定义类型上。对于同一个构建产物和同一组编码选项，结构体字段、切片元素和 map 内容应保持一致；如果输入切片顺序变了，输出当然也会变。

func writeStable(out io.Writer, value any) error {
    // Deterministic 只约束编码结果，不会替 Writer 吞掉写入错误。
    return jsonv2.MarshalWrite(out, value, jsonv2.Deterministic(true))
}

因此，比较两个 JSON 是否相同前，先确认两次调用使用了相同的 Go 值、相同的选项和相同的编码构建条件。不要把“map 键排序”解释成跨所有 Go 版本、编译参数和自定义实现都永远相同。

自定义 Marshaler 时要特别留意

如果类型实现了 Marshaler 或 MarshalerTo，实际 JSON 可能由自定义逻辑产生。此时调用方传入 Deterministic 并不代表自定义实现自动获得稳定结果；自定义实现需要遵守该选项，并在选项为真时自行保证确定性。

一个实用边界是：把自定义序列化器当作稳定性责任的最后一层。若它内部从 map、随机源、时间或非固定迭代顺序构造 JSON，就要在类型内部明确排序或固定输入，而不是只在外层重复调用 MarshalWrite。

什么时候该打开稳定输出

需要做字节级缓存键、快照文件比较、签名输入或可重复日志时，可以明确打开 json.Deterministic(true)。如果只是给客户端返回 JSON，业务通常更应该关心字段语义、兼容性和错误处理，而不是把字节顺序当成接口契约。

1. 确定比较目标是 JSON 语义还是完整字节；只有后者才需要稳定序列化。
2. 确认每次调用的 Go 值、选项和构建条件相同。
3. 检查自定义 Marshaler 是否真正读取并遵守确定性选项。
4. 检查 MarshalWrite 返回的 Writer 错误，避免保存不完整结果。

常见问题

Deterministic 会让 JSON 按业务字段顺序输出吗？ 不会。它提供确定性编码规则，map 的键会排序，但这不是业务自定义排序表。

只要打开 Deterministic，所有自定义类型都稳定了吗？ 不一定。自定义 Marshaler 需要自己尊重这个选项，否则外层调用无法替它修复内部随机逻辑。

MarshalWrite 返回 nil 就代表数据已经完整写入了吗？ 它表示编码和 Writer 写入过程没有报告错误；如果 Writer 实现返回错误，应按错误处理，不要继续使用不完整输出。

总结来说，MarshalWrite 解决“写到哪里”，Deterministic(true) 解决“同一输入如何稳定编码”。把 map、结构体、自定义 Marshaler 与 Writer 的责任分开，才能正确判断 JSON 是否真的适合做字节级比较。