Go netip.Addr.Unmap 什么时候需要处理 IPv4 映射地址

先给结论：只有当 netip.Addr 实际装的是 IPv4-mapped IPv6，例如 ::ffff:192.0.2.7，而业务又需要把它当作普通 IPv4 做统一比较、分组或序列化时，才需要调用 Unmap()。判断不要看字符串里有没有冒号，而应先看 Is4In6()。原生 IPv4 和普通 IPv6 调用 Unmap() 都会原样返回，但协议层确实需要保留 IPv6 身份时，不要为了“统一格式”强行转换。

官方参考：https://pkg.go.dev/net/netip/　https://go.dev/src/net/netip/netip.go

先判断地址形态：Is4、Is4In6 与 Is6 不是一回事

netip.Addr 把 IPv4-mapped IPv6 作为 IPv6 地址看待，所以 Is6() 为 true、BitLen() 为 128，而 Is4() 为 false。这正是很多判断代码出错的地方：看到一个 IPv4 语义的地址，却因为 Is4() 为 false 把它送进了普通 IPv6 分支。

Is4In6() 判断地址是否落在 RFC 4291 定义的 ::ffff:0:0/96 映射范围内。先分型，再决定是否规范化，比直接用 String() 拆分文本可靠。

package main

import (
	"fmt"
	"net/netip"
)

func describe(label string, ip netip.Addr) {
	// 先识别映射关系，再决定后续是否按 IPv4 处理。
	fmt.Printf("%s: %s, Is4=%v, Is4In6=%v, Is6=%v, bits=%d\\n",
		label, ip, ip.Is4(), ip.Is4In6(), ip.Is6(), ip.BitLen())
}

func main() {
	// MustParseAddr 只用于这里的固定示例；外部输入应使用 ParseAddr 检查错误。
	describe("IPv4", netip.MustParseAddr("192.0.2.7"))
	describe("mapped", netip.MustParseAddr("::ffff:192.0.2.7"))
	describe("IPv6", netip.MustParseAddr("2001:db8::7"))
}

Unmap 的正确落点：统一键值前转换，协议语义中谨慎保留

Unmap() 的语义很窄：如果地址是 IPv6 包裹的 IPv4，就返回包裹的 IPv4；否则返回原值。它不是网络连接转换，也不会把普通 IPv6 压缩成 IPv4。正因为它是值类型上的规范化操作，适合放在“进入统一地址集合”的边界，而不是放在所有网络代码的开头。

例如来自不同套接字或代理层的地址要作为同一个客户端键时，可以显式做一次规范化：

package main

import (
	"fmt"
	"net/netip"
)

func canonicalClientKey(raw string) (netip.Addr, error) {
	// ParseAddr 负责输入校验；Unmap 只负责去掉 IPv4-mapped IPv6 外壳。
	ip, err := netip.ParseAddr(raw)
	if err != nil {
		return netip.Addr{}, fmt.Errorf("parse client address: %w", err)
	}
	return ip.Unmap(), nil
}

func main() {
	// 两种输入会得到同一个 IPv4 规范化键，普通 IPv6 仍保留 IPv6。
	for _, raw := range []string{"192.0.2.7", "::ffff:192.0.2.7", "2001:db8::7"} {
		key, err := canonicalClientKey(raw)
		if err != nil {
			fmt.Println(err)
			continue
		}
		fmt.Println(raw, "=>", key)
	}
}

转换后用 As4、BitLen 和 String 复核结果

确认已经进入 IPv4 分支后，As4() 可以取得 4 字节数组，BitLen() 应为 32，String() 会输出点分十进制。As4() 对零值或普通 IPv6 会 panic，因此不要跳过 Is4() 或 Is4In6() 的判断直接调用。

// normalizeIPv4 只接受原生 IPv4 或 IPv4-mapped IPv6，避免 As4 对普通 IPv6 触发 panic。
func normalizeIPv4(raw string) ([4]byte, error) {
	ip, err := netip.ParseAddr(raw)
	if err != nil {
		return [4]byte{}, err
	}
	ip = ip.Unmap()
	if !ip.Is4() {
		return [4]byte{}, fmt.Errorf("not an IPv4 address: %s", ip)
	}
	return ip.As4(), nil
}

常见问题

调用 Unmap 后，普通 IPv6 会变成什么？

不会变化。文档定义的是“映射地址去掉前缀”，其他地址原样返回。

为什么 Is4() 对 ::ffff:192.0.2.7 返回 false？

因为它在 netip 中仍按 IPv6 地址表示；先用 Is4In6() 识别，再调用 Unmap() 后，Is4() 才会变为 true。

能不能所有地址都无条件 Unmap？

可以作为无副作用的值规范化步骤，但是否应该这样做取决于业务。需要区分地址族、协议来源或 IPv6 区域时，应保留原值并只在比较键或 IPv4 专用出口处转换。

判断 Unmap() 是否该出现，核心不是“字符串像不像 IPv4”，而是当前边界是否要把 IPv4-mapped IPv6 当成 IPv4。先用 Is4In6() 识别，按用途选择规范化位置，再用 Is4()、As4() 和 BitLen() 复核，能避开地址族判断和序列化中的隐性分歧。