maps.Equal 为什么不能比较浮点 NaN 值

maps.Equal 并不是“不能执行”浮点 NaN 比较，而是会按 Go 的 == 规则得到不相等。NaN 具有非自反特性，即使两个 map 在相同键下都存放 math.NaN()，值比较仍为 false，所以整个 map 比较也返回 false。

官方文档：https://pkg.go.dev/maps

NaN 作为 map 的值时，用 maps.EqualFunc 自定义“两个 NaN 视为相等”的规则；NaN 作为 map 的键时，EqualFunc 也无能为力，因为键查找仍使用 ==，应改用稳定业务键或在写入前拒绝 NaN。

故障表现：两份结果看起来一样，Equal 却是 false

问题通常出现在指标、传感器或计算结果中。两个服务都生成了同样的键集合，普通数值完全一致，缺失或无效结果都用 NaN 表示。日志里看起来两份 map 一样，测试却失败。

package main

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

func main() {
	left := map[string]float64{
		"temperature": 21.5,
		"humidity":    math.NaN(),
	}
	right := map[string]float64{
		"temperature": 21.5,
		"humidity":    math.NaN(),
	}

	// 普通值相等，但两个 NaN 用 == 比较仍是不相等。
	fmt.Println(maps.Equal(left, right))
}

结果为 false。影响面不只限于单元测试：如果 map 相等性被用于缓存命中、配置变更检测或计算结果去重，同样会产生“内容没变化却反复刷新”的现象。

根因：Equal 的值比较就是 ==

Go 标准库文档明确说明，maps.Equal 判断两个 map 是否包含相同键值对，值使用 == 比较。对普通可比较值，这个规则简单明确；但 IEEE 754 的 NaN 不等于任何数，包括它自己。

nan := math.NaN()

// NaN 具有非自反性，下面两个表达式都会得到 false。
fmt.Println(nan == nan)
fmt.Println(math.NaN() == math.NaN())

因此 maps.Equal 遇到相同键时，即使左右两边的值都属于 NaN，执行 leftValue == rightValue 仍得到 false。它没有做错，而是严格遵循值类型的相等运算。

修复 NaN 值：改用 maps.EqualFunc

maps.EqualFunc 允许调用方提供值比较函数。最小修复是：如果左右两值都是 NaN，就按业务规则视为相等；其他值仍使用精确的 ==。

package main

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

func equalFloat64(a, b float64) bool {
	if math.IsNaN(a) && math.IsNaN(b) {
		return true // 业务上把两个无效数值视为同一种状态
	}
	return a == b
}

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

	// EqualFunc 只替换值的比较规则。
	fmt.Println(maps.EqualFunc(left, right, equalFloat64))
}

这段代码会得到 true。判断函数保持了两个重要边界：一个 NaN 和一个普通数仍不相等；两个普通数只有精确相等时才返回 true。

近似相等不要和 NaN 规则混在一起

计算结果还可能需要容差比较。此时可以在同一比较函数中先处理 NaN，再处理无穷大，最后比较误差。不过容差属于业务定义，不能随便写一个固定值套用所有数据。

func equalFloat64Approx(a, b, epsilon float64) bool {
	if math.IsNaN(a) || math.IsNaN(b) {
		return math.IsNaN(a) && math.IsNaN(b) // 只允许 NaN 与 NaN 等价
	}
	if math.IsInf(a, 0) || math.IsInf(b, 0) {
		return a == b // 正负无穷必须方向一致
	}
	return math.Abs(a-b) 

如果数据尺度跨度很大，应采用相对误差或绝对误差与相对误差结合的策略。文章标题中的问题只需处理 NaN，没必要为了修一个边界顺便改变所有普通浮点数的比较语义。

NaN 作为键时为什么更麻烦

官方 maps 包说明指出，它不会特殊处理非自反键，例如浮点 NaN。更关键的是，maps.EqualFunc 只接管值的比较；键仍用 == 判断并执行 map 查找。因此，下面这种结构没有可靠的相等语义：

left := map[float64]string{
	math.NaN(): "missing",
}
right := map[float64]string{
	math.NaN(): "missing",
}

// 自定义值比较也无法修复 NaN 键，因为键仍按 == 查找。
same := maps.EqualFunc(left, right, func(a, b string) bool {
	return a == b
})
fmt.Println(same)

从类型约束看，float64 是 comparable，因此可以作为 map 键；但“允许作为键”不等于“所有浮点值都适合做稳定业务键”。NaN 的非自反性会让查找、去重和相等判断都难以符合直觉。

NaN 键应怎样改造

优先方案是不要让测量值直接承担标识职责。将传感器 ID、字段名、时间窗口或业务编号作为键，把浮点结果放在值中。这样既能保留 NaN，又能通过 EqualFunc 定义比较语义。

type MetricKey struct {
	SensorID string
	Field    string
}

metrics := map[MetricKey]float64{
	// 稳定业务字段做键，NaN 只放在值位置。
	{SensorID: "sensor-7", Field: "humidity"}: math.NaN(),
}

如果输入数据确实把浮点数作为索引，应在写入 map 前检查：

func putFinite(m map[float64]string, key float64, value string) error {
	if math.IsNaN(key) {
		return fmt.Errorf("NaN 不能作为稳定业务键")
	}
	m[key] = value
	return nil
}

另一种做法是将特殊状态规范化为枚举字段，例如 KindMissing，而不是用 NaN 同时表达“缺失”“无效”“未计算”和“溢出”。状态越明确，比较、序列化和排障越简单。

防止问题再次出现的检查清单

测试至少应覆盖五组输入：普通相等、普通不等、NaN 对 NaN、NaN 对普通数、正负无穷。若使用容差，再补上刚好等于阈值和略大于阈值的边界。

常见追问

两个 NaN 的位模式完全相同，maps.Equal 会返回 true 吗？

不会因为位模式相同而自动变成 true。maps.Equal 对值使用 ==，NaN 的比较结果仍是 false。若业务需要比较位模式，应明确使用 math.Float64bits，这与“两个 NaN 代表同一种无效状态”是不同语义。

EqualFunc 能同时比较不同值类型吗？

可以。它允许两个 map 的值类型不同，并由回调决定如何比较。但两个 map 的键类型相同，键依然使用 ==。

可以直接把所有 NaN 转成 0 吗？

通常不建议。0 是有效数值，NaN 常表示缺失、未定义或计算失败。直接转成 0 会丢失状态信息。更安全的做法是自定义相等规则，或使用“值 + 有效标记”的结构。

归根结底，问题不在 maps.Equal 本身，而在默认相等规则与业务语义不一致。NaN 是值时，用 EqualFunc 明确规则；NaN 是键时，重新设计键。把两种情况分开处理，比较结果才会稳定且可解释。