Go maps.Equal 比较包含 NaN 的值为什么返回 false

我排查 Go 映射断言时，最容易误判的一种情况是：两个 map[string]float64 看起来都放了 NaN，但 maps.Equal 返回了 false。这不是 map 没有遍历到键，也不是 NaN 被自动改写，而是 maps.Equal 明确使用 Go 的 == 比较值，而浮点 NaN 按 IEEE 754 规则连自身也不相等。

为什么 maps.Equal 遇到 NaN 值会返回 false

maps.Equal 的职责是判断两个映射是否包含相同的键值对；它要求值类型可比较，并按 == 比较对应值。NaN 是一种特殊的浮点值，nan == nan 的结果就是 false。因此下面的结果符合语言语义：

package main

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

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

	fmt.Println(left["score"] == right["score"]) // 中文注释：NaN 不等于自身
	fmt.Println(maps.Equal(left, right))          // 中文注释：Equal 沿用 ==，所以为 false
}

排查时我会先单独检查值，而不是先怀疑 map 的长度或遍历顺序。只要对应值是 NaN，普通相等判断就不会把它当作另一个 NaN 的同值。

先分清 NaN 是值还是 map 键

标题中的问题是 NaN 作为映射值。若把浮点数改成 map 的键，边界会更绕：NaN 不等于自身，因此用一个 NaN 变量去查另一个 NaN 键，并不能按普通“相同数字”理解。maps 包文档也明确提示，它对非自反键没有额外特殊处理。

这一区分很重要：给值比较加一个 NaN 分支，不能顺手推出“NaN 键也能正常查找”的结论。输入数据如果来自 JSON、传感器或统计计算，最好在进入 map 前决定 NaN 是保留、替换，还是转成带状态的结构。

需要 NaN 等价时用 maps.EqualFunc

如果业务定义“两个缺失的浮点结果都算相同”，应把这个定义写在比较函数里。maps.EqualFunc 负责遍历对应键，具体值是否相等由回调决定：

func equalFloat(a, b float64) bool {
	// 中文注释：业务先把两个 NaN 归为同一类，再处理普通数值。
	if math.IsNaN(a) && math.IsNaN(b) {
		return true
	}
	return a == b // 中文注释：非 NaN 值仍使用 Go 的浮点比较语义。
}

same := maps.EqualFunc(left, right, equalFloat)
fmt.Println(same) // 中文注释：业务规则将两个 NaN 视为相等。

比较函数还可以承载其他业务约定，例如把某个误差范围内的数值视为相等。但要谨慎：近似比较、NaN 等价、无穷大处理都改变了默认语义，应该在测试和接口文档中明确写出。

把相等规则固定在数据入口

实际项目里，最稳妥的做法不是在每个断言处临时补 math.IsNaN，而是在数据模型或比较器层固定约定。可以按下面的顺序检查：

1. 确认 NaN 出现于键还是值，并记录它代表缺失、无效还是计算未定义。
2. 默认使用 maps.Equal 时，接受它遵循 == 的结果。
3. 确需业务等价时，集中实现 EqualFunc 回调，并为 NaN、普通数值和边界值分别写测试。
4. 对外输出前决定是否把 NaN 转成可传输的状态字段，避免下游误把 false 当成 map 数据损坏。

这样处理后，false 就不再是模糊的异常信号，而是能回答“标准相等失败，还是业务相等规则尚未表达”的明确结果。

常见问题

maps.Equal 能直接比较包含 slice 的 map 吗？

不能。它要求值类型满足 comparable；如果值是 slice、map 或含有不可比较字段的结构体，应改用合适的自定义比较方案。

只调用 math.IsNaN 就能修复 maps.Equal 吗？

不能。math.IsNaN 只负责识别值，必须把识别结果接入 maps.EqualFunc 或其他业务比较逻辑。

两个普通 float64 一样，maps.Equal 还会失败吗？

如果键集合和其他对应值都一致，普通值按 == 比较通常可以相等；仍要单独考虑精度、无穷大以及 +0 和 -0 的业务要求。