Go JSON 测试用 map 比较为什么顺序不稳定

如果 Go 的 JSON 测试偶尔因为字段顺序不同而失败，先不要给 map 排序。通常真正的问题是把“对象是否相等”误写成了“字符串是否完全相同”。Go 的 map 遍历顺序本来就不应作为断言依据；JSON 对象的成员也没有业务上的先后。更稳妥的做法是先把 JSON 解码成结构化值，再比较 map、slice 或结构体。只有签名、协议快照等确实要求线缆字节一致的场景，才应该比较原始 JSON。

先分清：map 遍历乱序，JSON 对象没有顺序

Go 语言规范没有承诺 map 的迭代顺序。下面的代码每次都能拿到全部键，但输出顺序不能拿来写断言：

func keysText(values map[string]int) string {
    var b strings.Builder
    for key, value := range values {
        // 这里仅用于展示 map 的内容，不把遍历顺序当作契约。
        fmt.Fprintf(&b, "%s=%d;", key, value)
    }
    return b.String()
}

另一个容易混淆的点是 encoding/json 的实现细节。当前文档中，v1 包的 map 编码是确定性的；同一文档也说明 v2 默认使用非确定顺序，并提供 Deterministic 选项。即使 v1 输出看起来稳定，也不代表测试应该依赖成员排列：JSON 对象表达的是名称到值的映射，{"a":1,"b":2} 和 {"b":2,"a":1} 对多数接口语义相同。

结构一致时优先反序列化后比较

测试接口返回值时，可以先解码到与预期相同的类型。这样断言关注字段和值，测试失败也更接近业务问题：

func TestPayload(t *testing.T) {
    want := map[string]any{
        "name":  "Ada",
        "roles": []any{"admin", "reader"},
    }
    body := []byte(`{"roles":["admin","reader"],"name":"Ada"}`)

    var got map[string]any
    if err := json.Unmarshal(body, &got); err != nil {
        // 解码失败属于输入问题，应保留原始错误让测试直接失败。
        t.Fatalf("decode response: %v", err)
    }
    if !reflect.DeepEqual(got, want) {
        // 此处比较的是结构和值，不比较 JSON 文本的字段排列。
        t.Fatalf("payload mismatch: got %#v, want %#v", got, want)
    }
}

这个写法也会诚实暴露真正的差异：数组顺序不同、数字类型不同、null 与空 map 不同，都会被识别出来。若响应结构固定，优先定义一个 Go struct；它比 map[string]any 更早发现字段拼写和类型变化。只有在字段确实开放、需要动态扩展时，才使用 map。

需要看到差异时用 cmp.Diff，不要把 map 转字符串

当测试失败需要在 CI 日志里快速看出哪一项不同，可以使用 github.com/google/go-cmp/cmp。它直接比较 Go 值，不要求先把 map 排列成某种字符串：

func TestPayloadDiff(t *testing.T) {
    want := map[string]string{"env": "prod", "region": "cn"}
    got := map[string]string{"region": "cn", "env": "staging"}

    if diff := cmp.Diff(want, got); diff != "" {
        // Diff 保留字段路径，排查时比 fmt.Sprint(map) 更容易定位。
        t.Fatalf("payload mismatch (-want +got):\n%s", diff)
    }
}

如果项目不希望增加依赖，reflect.DeepEqual 足够完成相等判断；如果需要忽略某些字段、区分空切片与 nil，应该在测试里明确写出比较规则，而不是通过排序或字符串替换把差异“抹平”。

什么时候才应该比较原始 JSON 字节

字节级比较并非错误，但必须先回答“顺序和空白是不是协议的一部分”。请求签名、缓存键、黄金文件、兼容性回归可能需要稳定的线缆格式。这时应固定编码器、转义、数字表示和 map 顺序；涉及 encoding/json/v2 时，还要显式选择是否启用确定性编码。

普通 API 单元测试不要用 string(jsonBytes) 直接比较。可以先用 json.Unmarshal 验证语义，再单独添加一条格式契约测试。两类测试失败时含义不同：前者说明数据变了，后者说明传输表示变了。

相关问题

json.Marshal 的 map 输出是不是永远按字母排序？

不要把实现细节当成跨版本协议。v1 文档描述了确定性 map 编码，v2 则默认允许非确定顺序；需要稳定线缆格式时请显式配置并配套测试。

reflect.DeepEqual 能比较 map 吗？

可以。它比较 map 的键和值，不比较迭代顺序；但 nil map、空 map、不同数字类型和 slice 顺序仍可能造成不相等。

为什么不能先把 JSON 排序再比较？

简单按文本排序无法处理空白、转义、数字表示和嵌套结构。除非你实现的是有明确规范的 canonical JSON，否则解码后比较更可靠。