Go maps.Equal比较配置Map时的空Map与nil差异

配置 Map 从 JSON、环境变量或默认值合并逻辑进入业务层时，最容易误判的是“没有键”与“没有配置”是不是同一件事。结论先说：maps.Equal(nilMap, emptyMap) 返回 true，因为它比较的是键值对内容，而两者都没有键；但 nil 本身仍然可以承载“未配置”的业务语义，不能因此把所有 Map 都无条件归一化。

先看清 nil Map 与空 Map 的来源

下面三种 Map 在遍历和长度判断上很像，但初始化状态不同。声明后没有赋值的 nilMap 没有关联的底层表；emptyMap 通过 make 得到，可以安全写入；filledMap 则已经携带配置项。三者的共同点是读取和遍历安全，最大的操作差异是 nil map 不能直接赋值。

因此，len(m) == 0 只能说明当前没有键，不能证明这个字段从未配置过。若要判断“是否缺省”，使用 m == nil；若只关心有效配置项是否一致，交给 maps.Equal。

用 maps.Equal 比较配置内容

maps.Equal 的契约是比较两张 Map 是否包含相同的键值对，值使用 ==。实现上先比较 len，再遍历第一张 Map 去第二张 Map 查找同名键。因此 nil map 和空 map 都没有键，长度相同且遍历不产生差异，结果就是 true。

package main

import (
    "fmt"
    "maps"
)

func main() {
    var nilMap map[string]string
    emptyMap := make(map[string]string)
    desired := map[string]string{"region": "cn-east"}

    // 只比较配置项，不把 nil 与空 map 的初始化状态混入内容比较。
    fmt.Println(maps.Equal(nilMap, emptyMap)) // true
    fmt.Println(maps.Equal(emptyMap, desired)) // false

    // nil map 不能直接赋值；需要写入时先分配可写 map。
    if nilMap == nil {
        nilMap = make(map[string]string)
    }
    nilMap["region"] = "cn-east"
    fmt.Println(maps.Equal(nilMap, desired)) // true
}

这个写法适合“配置内容相同就算一致”的场景，例如缓存刷新前后比较有效键值，或者测试默认配置与解析结果。若配置值是切片、Map 或函数等不可比较类型，应改用 maps.EqualFunc，为每种值定义比较规则。

特殊值会改变“内容相同”的直觉

maps.Equal 并不深度推断值的业务含义，而是对值使用 Go 的 ==。字符串、整数和布尔值通常符合直觉；浮点 NaN 则不等于自身，所以两张 Map 都放入 NaN 时，比较可能返回 false。这与 nil、空 Map 的问题不同，排查时不要只看打印结果是否相同。

package main

import (
    "fmt"
    "maps"
    "math"
)

func main() {
    left := map[string]float64{"ratio": math.NaN()}
    right := map[string]float64{"ratio": math.NaN()}

    // NaN != NaN，不能把相同打印文本当成相等值。
    fmt.Println(maps.Equal(left, right)) // false
}

如果业务希望“两个 NaN 都表示未知，因此视为相同”，可以使用 maps.EqualFunc，在比较函数里先判断 math.IsNaN。这一步是业务规则，不要偷偷改写 maps.Equal 的通用语义。

需要区分 nil 语义时先做状态判断

配置接口常把 nil 表示“沿用系统默认值”，把空 Map 表示“明确清空所有覆盖项”。这时直接调用 maps.Equal 会丢掉这个区别，应该把状态判断放在内容比较之前，再决定是否把两者归一化。

package main

import (
    "maps"
)

func sameConfig(left, right map[string]string) bool {
    // 业务明确要求区分“未配置”和“已配置但为空”。
    if (left == nil) != (right == nil) {
        return false
    }
    // 两边状态一致后，再比较实际键值对。
    return maps.Equal(left, right)
}

如果产品定义里 nil 与空 Map 本来就等价，可以在入口统一转成空 Map；如果 nil 代表继承、空 Map 代表覆盖，则保留上面的判断，并在结构体字段或接口文档中写清楚。关键是先确认业务语义，再选择比较函数。

用测试表固定比较契约

配置比较最适合用表驱动测试，把状态和预期分开写出来。下面的断言覆盖了“内容相等”和“状态相等”两个层面，后续有人修改默认值合并逻辑时，失败用例能直接指出是哪条契约变了。

func TestSameConfig(t *testing.T) {
    tests := []struct {
        name string
        left, right map[string]string
        want bool
    }{
        {"nil and empty differ by state", nil, map[string]string{}, false},
        {"both nil", nil, nil, true},
        {"same entries", map[string]string{"mode": "safe"}, map[string]string{"mode": "safe"}, true},
    }

    for _, tc := range tests {
        t.Run(tc.name, func(t *testing.T) {
            // 使用同一业务函数验证状态判断和内容比较的组合结果。
            if got := sameConfig(tc.left, tc.right); got != tc.want {
                t.Fatalf("sameConfig() = %v, want %v", got, tc.want)
            }
        })
    }
}

如果你的契约只比较内容，把第一条的预期改成 true，并直接测试 maps.Equal；如果还要区分继承状态，就保留 sameConfig 这样的薄封装，避免调用方各自解释 nil。

相关问题

nil map 可以 range 吗？

可以。对 nil map 遍历不会产生元素，len 也是 0，但写入前仍要先用 make 初始化。

maps.Equal 能比较 map[string][]byte 吗？

不能直接用，因为切片不可比较。可以调用 maps.EqualFunc，在比较函数中使用 bytes.Equal。

为什么打印出来一样，比较结果却不同？

优先检查值类型是否含 NaN，或比较规则是否把 nil 作为业务状态。打印只展示值，不会告诉你初始化状态和比较契约。