Go netip.Addr IPv4 映射地址比较为什么不相等怎样构造最小复现

如果日志里同时出现 192.0.2.1 和 ::ffff:192.0.2.1，不要只看字符串就判断它们一定能用 == 比较为相等。netip.Addr 保留了地址族信息：前者是原生 IPv4，后者是 IPv4 映射 IPv6。只要业务边界要求把它们当成同一个 IPv4，就在比较、去重或作为 map 键之前统一调用 Unmap()。

最小修复就是：解析后先执行 addr = addr.Unmap()，再做相等比较或写入 map。Unmap 只移除 IPv4 映射 IPv6 的前缀，普通 IPv4 和真正的 IPv6 都不会被错误改写。

本文解决：构造一个可读的最小复现，解释 Is4、Is4In6、BitLen 和 Unmap 的关系，并把这个边界固化为 Go 测试。

先把“不相等”复现出来

两个输入都代表文档示例网段里的同一组 IPv4 数值，但解析后的 Addr 形态不同。最小复现只保留地址族判断和比较结果：

package main

import (
	"fmt"
	"net/netip"
)

func main() {
	plain := netip.MustParseAddr("192.0.2.1")
	mapped := netip.MustParseAddr("::ffff:192.0.2.1")

	// 输出地址族线索，先确认不是字符串格式造成的错觉。
	fmt.Printf("plain=%s Is4=%v Is4In6=%v BitLen=%d\n", plain, plain.Is4(), plain.Is4In6(), plain.BitLen())
	fmt.Printf("mapped=%s Is4=%v Is4In6=%v BitLen=%d\n", mapped, mapped.Is4(), mapped.Is4In6(), mapped.BitLen())

	// Addr 是可比较值，但不同地址族表示不会因为承载同一 IPv4 而自动相等。
	fmt.Printf("plain == mapped: %v\n", plain == mapped)
}

预期现象是：plain.Is4() 为 true、plain.BitLen() 为 32；映射地址的 Is4() 为 false、Is4In6() 为 true、BitLen() 为 128，最后的比较结果为 false。这里的关键不是 Addr 不能比较，而是比较前没有统一表示。

为什么字符串相近，Addr 却不是同一个值

netip.Addr 是小型、不可变且可比较的值类型。它的比较语义会保留 IPv4、IPv6 以及 IPv4 映射 IPv6 的差异。官方文档还特别说明，映射 IPv6 会被视为 IPv6，因此 Is6() 会为真，Is4() 不会把它当作原生 IPv4。

这也解释了两个容易混淆的判断：

所以，直接把 Addr 放进缓存或 map 时，可能得到两个键；先调用 String() 再比较也只是把问题转移到字符串规范化，不能替代明确的地址族策略。

用 Unmap 统一比较边界

Unmap() 的语义很窄：如果 Addr 是 IPv4 映射 IPv6，就移除映射前缀并返回被包裹的 IPv4；否则原样返回。这个特性适合放在输入适配层，而不是散落在每个业务判断里。

package addrkey

import "net/netip"

// Canonical 将映射 IPv6 归一化为 IPv4，普通 IPv4 和真实 IPv6 保持原形。
func Canonical(addr netip.Addr) netip.Addr {
	return addr.Unmap()
}

// SameIP 只比较规范化后的地址值，避免不同输入形态产生两个业务结果。
func SameIP(left, right netip.Addr) bool {
	return Canonical(left) == Canonical(right)
}

如果业务确实要区分“原生 IPv4”和“映射 IPv6”这两类输入，就不要调用这个规范化函数；例如审计原始协议形态时，Is4In6() 本身就是有用信息。反过来，访问控制、去重、客户端标识等只关心 IPv4 数值的场景，应在进入 map 或比较函数前统一。

把故障边界写成回归测试

测试不要只覆盖两个相等输入，还要保留一个真实 IPv6，证明规范化函数不会把所有地址都强行转换成 IPv4：

package addrkey

import (
	"net/netip"
	"testing"
)

func TestSameIP(t *testing.T) {
	tests := []struct {
		name string
		left string
		right string
		want bool
	}{
		{"原生 IPv4 与映射 IPv6", "192.0.2.1", "::ffff:192.0.2.1", true},
		{"不同 IPv4", "192.0.2.1", "192.0.2.2", false},
		{"真实 IPv6", "2001:db8::1", "2001:db8::1", true},
	}

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			left := netip.MustParseAddr(tt.left)
			right := netip.MustParseAddr(tt.right)
			// 断言业务比较，而不是断言字符串长得相似。
			if got := SameIP(left, right); got != tt.want {
				t.Fatalf("SameIP(%q, %q) = %v, want %v", tt.left, tt.right, got, tt.want)
			}
		})
	}
}

运行测试时只需执行：

# 在包目录执行回归测试，确认三种地址形态的边界
go test ./...

如果代码把 Canonical 去掉，第一组测试会立即暴露比较回归；如果误把真正 IPv6 转换成 IPv4，第三组测试也会失败。

常见疑问

直接比较 String() 能解决吗？

不能稳定解决。字符串比较依赖输入是否已经采用同一种文本规范，无法表达业务是否要区分地址族。对 IPv4 等价语义，优先比较 Unmap() 的结果。

Unmap 会把所有 IPv6 变成 IPv4 吗？

不会。它只处理 IPv4 映射 IPv6，普通 IPv6 会原样返回；因此它适合作为窄范围的规范化操作。

总结

192.0.2.1 与 ::ffff:192.0.2.1 的数值关联不等于 netip.Addr 表示相等。先用 Is4、Is4In6 和 BitLen 识别地址族，再按业务目标决定是否调用 Unmap；需要 IPv4 等价比较时，把规范化放在比较和 map 键的共同入口，并用表驱动测试锁住这个边界。