Go netipIPv4-mapped IPv6 地址比较不相等怎么办

我在排查 IP 白名单和客户端缓存键时遇到过一个很容易误判的现象：192.0.2.1 与 ::ffff:192.0.2.1 看起来指向同一个 IPv4 地址，但用 netip.Addr 直接比较却不相等。根因不是字符串格式化，而是两者在 netip 内部属于不同的地址族表示。

如果业务语义是“映射形式也算这个 IPv4 端点”，就把比较两侧和 map 键入口统一调用 Addr.Unmap()；如果协议必须区分 IPv4 与 IPv6，则不要做这一步。

先看影响面：比较和 map 查找都会踩坑

netip.Addr 是可比较值类型，可以直接使用 ==，也可以作为 map 键。这正是它方便的地方，也是问题容易扩散的地方：一次输入来自连接层，得到的是 IPv4-mapped IPv6；另一次输入来自配置文件，得到的是普通 IPv4。两者如果未经统一，就会出现白名单判断失败、缓存 miss 或去重结果多出一份。

为什么 == 比较会失败：两个 Addr 不是同一种表示

普通 IPv4 解析后是 32 位地址，Is4() 返回 true；映射地址仍然是 IPv6 表示，BitLen() 是 128，Is4() 返回 false，但 Is4In6() 返回 true。因此 String() 保留了 ::ffff: 前缀，== 也不会替你猜测“这两种表示应该等价”。

package main

import (
	"fmt"
	"net/netip"
)

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

	// 用属性确认两者的地址族表示，而不是只看打印出来的文本。
	fmt.Println(v4.Is4(), v4.BitLen())
	fmt.Println(mapped.Is4(), mapped.Is4In6(), mapped.BitLen())

	// 比较的是 Addr 表示本身，映射前缀不会自动被忽略。
	fmt.Println(v4 == mapped)
	fmt.Println(v4.Compare(mapped))
}

这里的 Compare 也不能当作“忽略地址族”的比较器：返回 0 的条件仍然是两个 Addr 相等。排查时先看 Is4In6 和 BitLen，比把两个 String 直接打印出来更容易定位根因。

用 Unmap 统一比较和 map 键

Unmap 的语义很窄：只有 IPv4-mapped IPv6 会被还原为被包裹的 IPv4，普通 IPv6 会原样返回。可以把它放在解析边界，形成一个所有调用方都复用的规范化函数。

package main

import (
	"fmt"
	"net/netip"
)

// endpointKey 把需要视为同一 IPv4 端点的两种输入统一成一个 Addr。
func endpointKey(text string) (netip.Addr, error) {
	ip, err := netip.ParseAddr(text)
	if err != nil {
		// 解析失败要返回给调用方，不能用零值伪装成合法地址。
		return netip.Addr{}, err
	}
	return ip.Unmap(), nil
}

func main() {
	a, _ := endpointKey("192.0.2.1")
	b, _ := endpointKey("::ffff:192.0.2.1")

	// 规范化后既能比较，也能稳定命中同一个 map 键。
	clients := map[netip.Addr]string{a: "client-a"}
	fmt.Println(a == b, clients[b])
}

生产代码不要像示例一样忽略错误，示例只是突出比较关系。更稳妥的做法是让白名单、缓存和去重都从同一个 endpointKey 入口取键，避免某个调用点忘记规范化。若需要排序，先对两侧 Unmap，再调用 Compare；不要用带映射前缀的字符串排序结果代替地址语义。

修复边界：什么时候不能直接 Unmap

第一，若协议或策略必须区分 IPv4 与 IPv6，地址族就是业务字段，此时应保留原始 Addr，而不是把映射形式折叠掉。第二，若日志需要还原网络层的原始表示，规范化键和展示文本应分开保存。第三，::ffff:192.0.2.1 是映射地址，不等同于任意 IPv6 地址；只有 Is4In6() 为真时才有 IPv4 语义。

相关问题

为什么不直接比较 String？

因为字符串比较只是在比较文本，不能表达地址族和区域等语义。把输入先解析成 netip.Addr，再按业务需要决定是否 Unmap，更容易复用到比较、map 和白名单。

Unmap 会把普通 IPv6 变成 IPv4 吗？

不会。它只移除 IPv4-mapped IPv6 的映射前缀，其他地址保持不变；真正的关键是先明确业务是否把两种表示视为同一端点。