Go net/netip 怎样避免 IP 地址字符串比较误判

Go 中如果直接比较 IP 地址字符串，最容易把“写法不同”和“地址不同”混为一谈。IPv6 可以使用压缩写法，IPv4 还可能以 IPv4-mapped IPv6 的形式出现，所以更稳妥的做法是：先用 netip.ParseAddr 解析成 netip.Addr，再按地址值比较；只有在展示、日志或跨系统传输时，才把它格式化成字符串。

核心结论：字符串是输入和展示格式，netip.Addr 才是比较对象。需要把 IPv4-mapped IPv6 统一成 IPv4 时，再显式调用 Unmap，不要在字符串层面手工替换。

先解析，再比较 Addr 值

netip.Addr 是可比较的值类型，可以直接用 == 做相等判断，也可以用 Compare 做排序，还能直接作为 map 的键。这样做的关键是让解析器负责处理 IPv6 的规范表示，而不是让业务代码自己拆冒号、补零或压缩字符串。

package main

import (
	"fmt"
	"net/netip"
)

func main() {
	left, err := netip.ParseAddr("2001:0db8:0:0:0:0:0:1")
	if err != nil {
		// 外部输入必须保留错误，不能把零值当成合法地址继续处理。
		panic(err)
	}
	right, err := netip.ParseAddr("2001:db8::1")
	if err != nil {
		// 第二个地址同样经过解析，避免混入未规范化的字符串比较。
		panic(err)
	}

	fmt.Println(left == right)       // 两种 IPv6 写法表示同一个地址
	fmt.Println(left.Compare(right)) // 相等时返回 0

	seen := map[netip.Addr]string{
		left: "同一个地址的记录",
	}
	fmt.Println(seen[right]) // 可以用另一个文本写法取到同一条记录
}

这里的比较对象始终是 Addr。如果输入来自 HTTP 参数、配置文件或日志，应该检查 ParseAddr 的错误；MustParseAddr 更适合测试中写死且确定合法的常量，不适合直接接收用户输入。

String 负责稳定展示，不负责替代身份判断

Addr.String() 会输出地址的规范文本，例如把 IPv6 的连续零段压缩成 ::。这很适合日志、缓存键或接口响应，但它的职责是格式化。业务判断仍然应该在 Addr 层完成，不要先把不同来源的字符串拼接、大小写处理或手工补零后再比较。

func canonicalText(raw string) (string, error) {
	addr, err := netip.ParseAddr(raw)
	if err != nil {
		// 返回原始解析错误，让调用方决定是拒绝、记录还是提示用户。
		return "", err
	}
	// String 只负责把已经解析成功的地址转换成稳定文本。
	return addr.String(), nil
}

func sameAddress(a, b string) (bool, error) {
	left, err := netip.ParseAddr(a)
	if err != nil {
		// 左侧失败时立即返回，避免把无效输入与合法地址混淆。
		return false, err
	}
	right, err := netip.ParseAddr(b)
	if err != nil {
		// 两个输入都要独立解析，不能只规范化其中一个。
		return false, err
	}
	return left == right, nil
}

如果你需要生成缓存键，建议明确写出键的语义：是“原始协议形态的地址”，还是“归一化后的地址”。前者可以直接使用 addr.String()；后者要先执行 Unmap，否则 192.0.2.1 与 ::ffff:192.0.2.1 可能落入两个键。

IPv4 映射地址要先决定归一化策略

netip 会区分普通 IPv4、普通 IPv6 和 IPv4-mapped IPv6。对 ::ffff:192.0.2.1 来说，Is4() 返回 false，而 Is4In6() 返回 true；调用 Unmap() 后，才会得到普通的 IPv4 Addr。这不是“格式美化”，而是一次明确的身份归一化。

func normalizedIPv4(raw string) (netip.Addr, error) {
	addr, err := netip.ParseAddr(raw)
	if err != nil {
		// 输入不合法时不返回一个看似可用的零值地址。
		return netip.Addr{}, err
	}
	// Unmap 对普通 IPv4 和普通 IPv6 不改变地址，只去掉 IPv4 映射前缀。
	return addr.Unmap(), nil
}

func describe(raw string) error {
	addr, err := netip.ParseAddr(raw)
	if err != nil {
		// 解析失败与“地址是 0.0.0.0”是两种不同业务状态。
		return err
	}
	fmt.Printf("原文=%q Is4=%v Is4In6=%v 归一化=%q\n",
		raw, addr.Is4(), addr.Is4In6(), addr.Unmap().String())
	return nil
}

如果程序需要记录客户端真实的协议形态，保留 addr，并用 Is4In6() 做分类；如果程序只关心 IPv4 地址身份，例如统一做白名单匹配或聚合统计，则使用 addr.Unmap() 后再比较和生成键。不要把这两个目标混成一个“统一格式”。

无效输入、零值和特殊地址要分开处理

netip.Addr{} 是零值，不是 0.0.0.0，也不是 ::。解析失败时，推荐直接返回错误；只有当业务确实允许空地址作为“尚未设置”状态时，才保存零值，并用 IsValid() 检查它。

func acceptAddress(raw string) (netip.Addr, error) {
	if raw == "" {
		// 空字符串是否代表“未设置”由业务决定，这里选择显式拒绝。
		return netip.Addr{}, fmt.Errorf("地址不能为空")
	}
	addr, err := netip.ParseAddr(raw)
	if err != nil {
		// 不用 Addr.String() 的 "invalid IP" 作为错误判断依据。
		return netip.Addr{}, fmt.Errorf("解析地址 %q: %w", raw, err)
	}
	return addr, nil
}

func validState(addr netip.Addr) string {
	if !addr.IsValid() {
		// 零值只表示没有初始化地址，不等于未指定地址。
		return "未设置"
	}
	if addr.IsUnspecified() {
		// 0.0.0.0 和 :: 是合法的未指定地址。
		return "未指定地址"
	}
	return addr.String()
}

特别要注意：String() 对零值会返回 invalid IP，这是一种展示文本，不应该被当作输入校验接口。外部输入的合法性由 ParseAddr 的错误决定，业务状态由 IsValid() 和 IsUnspecified() 等方法表达。

按场景选择比较方式

常见问题

为什么两个 IPv6 字符串看起来不同，却应该判断为相同？

IPv6 允许压缩连续的零段。把两段文本都解析成 netip.Addr 后，再使用 == 比较，业务代码就不需要理解每一种合法写法。

什么时候必须调用 Unmap？

当业务把普通 IPv4 与 IPv4-mapped IPv6 视为同一个身份时调用，例如统一统计或匹配 IPv4 规则；如果需要保留连接或协议层的原始形态，则不要提前归一化。

可以直接把 Addr 当 map 的 key 吗？

可以。netip.Addr 是可比较的值类型，适合作为 map 键；但 map 的键语义仍由业务决定，是否先 Unmap 会影响去重结果。

小结

避免 IP 地址字符串比较误判，可以记住三句话：输入先 ParseAddr，身份用 Addr 值判断，展示再用 String()。遇到 IPv4-mapped IPv6 时，用 Is4In6() 识别，用 Unmap() 明确归一化；遇到无效输入和零值时，分别用 error 与 IsValid() 表达状态。