Go net/netip.Addr.Unmap 怎样统一 IPv4-mapped IPv6 地址

我在整理代理层的客户端地址时遇到过一个很容易忽略的情况：同一个 IPv4，进入 Go 程序后可能以 192.0.2.10 出现，也可能以 ::ffff:192.0.2.10 出现。它们都指向 IPv4 语义，但在 net/netip 中并不是同一种地址表示。

这个场景直接用 netip.Addr.Unmap() 处理。它只会移除 IPv4-mapped IPv6 的映射前缀，把包装在 IPv6 里的 IPv4 还原成普通 IPv4；普通 IPv4 和真正的 IPv6 都保持原样。这样再做比较、日志归一化或构造 map 键，规则会更稳定。

官方地址：https://pkg.go.dev/net/netip#Addr.Unmap

我第一次踩坑：同一个 IPv4 可能有两种 Addr 形态

netip.Addr 同时表示 IPv4 和 IPv6。真正容易混淆的是 ::ffff:0:0/96 这个 IPv4-mapped IPv6 范围：它看起来是 IPv6，实际携带了一个 IPv4 地址。官方文档明确说明，Is4() 对这种映射地址返回 false，需要用 Is4In6() 单独识别。

因此我通常先判断地址形态，再决定是否统一：

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    samples := []string{"192.0.2.10", "::ffff:192.0.2.10", "2001:db8::10"}

    for _, text := range samples {
        // ParseAddr 负责把文本解析成值类型；输入错误时不要继续使用零值 Addr。
        ip, err := netip.ParseAddr(text)
        if err != nil {
            fmt.Printf("%s: parse error: %v\n", text, err)
            continue
        }

        // Is4In6 专门识别映射地址；普通 IPv4 和普通 IPv6 走不同分支。
        fmt.Printf("%-20s Is4=%-5v Is4In6=%-5v Is6=%-5v BitLen=%d\n",
            text, ip.Is4(), ip.Is4In6(), ip.Is6(), ip.BitLen())
    }
}

这里的重点不是把所有地址都当作 IPv4，而是先保留地址的真实形态。普通 IPv4 的 Is4() 为 true，映射地址的 Is4In6() 为 true 且 Is4() 仍为 false，真正的 IPv6 则既不是普通 IPv4，也不是映射 IPv6。官方实现还把映射地址的 BitLen() 视为 128，正是因为它在归一化前仍是 IPv6 表示。

把地址统一成可比较的键

当业务目标是“同一客户端只保留一个地址键”时，我会在进入缓存、限流或审计字段的边界调用 Unmap()，而不是在每个比较点临时写字符串判断：

package main

import (
    "fmt"
    "net/netip"
)

func canonicalAddr(text string) (netip.Addr, error) {
    // 解析失败直接返回错误，避免把 invalid IP 当作业务键写入缓存。
    ip, err := netip.ParseAddr(text)
    if err != nil {
        return netip.Addr{}, err
    }

    // Unmap 只折叠 IPv4-mapped IPv6；普通 IPv4 和普通 IPv6 不会被改写。
    return ip.Unmap(), nil
}

func main() {
    for _, text := range []string{"192.0.2.10", "::ffff:192.0.2.10", "2001:db8::10"} {
        ip, err := canonicalAddr(text)
        if err != nil {
            fmt.Println("invalid:", text, err)
            continue
        }

        // Addr 是可比较值类型，可以直接作为 map 的键；String 只用于展示。
        fmt.Printf("input=%-20s canonical=%-16s bits=%d\n", text, ip.String(), ip.BitLen())
    }
}

对前两个输入，归一化后的结果都属于普通 IPv4，字符串显示为同一个点分十进制地址；对 2001:db8::10，Unmap() 返回原来的 IPv6。这个“只折叠映射地址”的行为，正是它适合作为边界归一化函数的原因。

As4、String 和 BitLen 要跟着归一化结果理解

有一次我只改了日志格式，却忘了下游还会调用 As4()，于是把“能显示成 IPv4”误认为“已经是 IPv4 类型”。这几个方法关注的事情不同：

As4() 的语义是取得 IPv4 或 IPv4-in-IPv6 的四字节表示，它不是判断地址类别的方法。更稳妥的做法是：需要类型判断时使用 Is4() 或 Is4In6()，需要四字节数据时再调用 As4()。对未知输入直接调用 As4()，如果它是普通 IPv6，会触发 panic，所以不能把它当成无条件转换函数。

我最后保留的三个边界

• 它不是字符串替换。 Unmap() 作用于 Addr 值，不会修改原字符串，也不会把任意包含 ::ffff: 的文本强行当作 IPv4。
• 它不是 CIDR 规范化。 如果任务是计算网段或掩码，应使用 netip.Prefix 相关 API；不要把地址归一化和前缀规划混为一谈。
• 它不是所有 IPv6 的降级。 只有 IPv4-mapped IPv6 会折叠，真正的 IPv6、带 IPv6 zone 的地址和无效零值仍需要按各自语义处理。

我的实践结论是：在“地址进入业务键”的单一边界调用一次 Unmap()，然后让后续代码只处理规范化后的 netip.Addr。如果业务必须保留原始输入，则同时保存原文和规范化键，不要用规范化结果覆盖审计字段。

相关问题

IPv4-mapped IPv6 为什么 Is4() 返回 false？

因为它在 netip.Addr 中仍然是 IPv6 形态。先用 Is4In6() 识别，再按业务需要调用 Unmap()。

Unmap 会不会改变普通 IPv6？

不会。官方定义是：非 IPv4-mapped IPv6 返回原地址不变。

什么时候应该保留映射形式？

如果你需要保留网络层原始地址族、套接字上下文或审计输入，就保留原值；只有在比较、聚合、缓存键等明确要求统一时才做归一化。