Go 的 netip.Addr 比 net.IP 更适合做地址键：比较、零值与 IPv4 映射边界

做 IP 白名单或连接计数时，地址经常要放进 map。如果继续把 net.IP 当键，代码会先遇到“切片不可比较”，改成字符串又要承担格式统一和额外转换。Go 1.18 引入的 net/netip 提供了值类型 netip.Addr：它不可变、可比较，适合直接作为地址键。

需要把“规范化后的 IP 地址”当作 map 键时，优先使用 netip.Addr；但要先判断 Addr.IsValid()，并明确 IPv4 地址与 IPv4-mapped IPv6 地址是否要视为同一个地址。

先看一个白名单查询的实际问题

假设服务每次收到连接后都要查一次允许访问的地址。最小实现通常是：

allowed := map[netip.Addr]string{
    netip.MustParseAddr("192.0.2.10"): "office-a",
}

addr, err := netip.ParseAddr("192.0.2.10")
if err != nil {
    return err
}
name, ok := allowed[addr]
if !ok {
    return fmt.Errorf("address %s is not allowed", addr)
}
fmt.Println(name)

这里的关键不是语法短，而是键的身份稳定。Addr 是值，解析后的地址不会因为某个外部字节切片被复用而改变；同一个地址可以安全地用于查表、计数和缓存。

为什么 netip.Addr 能直接做 map 键

net.IP 的本质是 []byte，切片不能用 == 做值比较，也不能直接作为 map 键。即使使用 bytes.Equal，map 查找仍然要自己维护规范化规则：4 字节 IPv4、16 字节 IPv4、IPv4-mapped IPv6 是否一致，都会变成调用方的责任。

netip.Addr 把地址表示收进一个小的值类型，官方文档明确它不可变且可比较。因此以下代码的比较和查找都按值完成：

left := netip.MustParseAddr("2001:db8::10")
right := netip.MustParseAddr("2001:0db8:0:0:0:0:0:10")

fmt.Println(left == right) // true

hits := map[netip.Addr]int{left: 1}
hits[right]++
fmt.Println(hits[left]) // 2

这个结果适合做地址计数，但不要把它误读成“所有地址文本都自动拥有业务上的同一身份”。带 IPv6 zone 的地址、IPv4-mapped IPv6，以及业务层的代理地址仍然需要明确规则。

零值不是 0.0.0.0：先做有效性检查

从函数返回地址时，netip.Addr{} 是很方便的零值，但它不是一个可路由的 IP。官方定义中，零值无效，并且与 IPv4 unspecified 地址 0.0.0.0 和 IPv6 unspecified 地址 :: 都不同。

var zero netip.Addr
unspecified4 := netip.IPv4Unspecified()
unspecified6 := netip.IPv6Unspecified()

fmt.Println(zero.IsValid()) // false
fmt.Println(unspecified4.IsValid()) // true
fmt.Println(zero == unspecified4, zero == unspecified6) // false false

所以缓存查找、白名单加载和配置解析都应该把无效地址当成输入错误，而不是默认为 0.0.0.0：

func keyOf(raw string) (netip.Addr, error) {
    addr, err := netip.ParseAddr(raw)
    if err != nil {
        return netip.Addr{}, fmt.Errorf("parse client address %q: %w", raw, err)
    }
    if !addr.IsValid() {
        return netip.Addr{}, errors.New("invalid IP address")
    }
    return addr, nil
}

从 net.IP 迁移时，最容易漏掉 IPv4 映射

旧接口返回 net.IP 时，可以使用 netip.AddrFromSlice 转换 4 字节或 16 字节表示：

func addrFromLegacy(ip net.IP) (netip.Addr, error) {
    addr, ok := netip.AddrFromSlice(ip)
    if !ok {
        return netip.Addr{}, fmt.Errorf("unsupported IP length: %d", len(ip))
    }
    return addr, nil
}

但转换成功不代表语义已经统一。AddrFrom16 对 IPv4-mapped IPv6 会保留 IPv6 身份；如果系统希望把 ::ffff:192.0.2.10 和 192.0.2.10 归到同一个键，需要显式调用 Unmap：

mapped := netip.MustParseAddr("::ffff:192.0.2.10")
plain := netip.MustParseAddr("192.0.2.10")

fmt.Println(mapped == plain) // false
fmt.Println(mapped.Unmap() == plain) // true

这是地址键设计中最应该写进测试的边界。若业务要区分两种地址族，不要调用 Unmap；若业务只关心最终 IPv4 客户端，就在进入 map 前统一处理。

把转换规则固定在入口，查表阶段只接受 Addr

推荐把规范化放在边界函数里，后面的缓存、统计和授权代码只处理 netip.Addr。这样不会出现一部分调用方用字符串、一部分用 net.IP 的混合键。

type Allowlist struct {
    values map[netip.Addr]string
}

func NewAllowlist(raw []string, unmapIPv4 bool) (*Allowlist, error) {
    values := make(map[netip.Addr]string, len(raw))
    for _, text := range raw {
        addr, err := netip.ParseAddr(text)
        if err != nil {
            return nil, err
        }
        if unmapIPv4 {
            addr = addr.Unmap()
        }
        values[addr] = text
    }
    return &Allowlist{values: values}, nil
}

查找方法要先拒绝无效零值，再读取 map 的布尔结果：

func (a *Allowlist) Contains(addr netip.Addr) bool {
    if !addr.IsValid() {
        return false
    }
    _, ok := a.values[addr]
    return ok
}

用小测试验收比较、零值和映射边界

这类代码不需要先做复杂压测，先把身份规则锁进测试。至少覆盖规范化文本、无效零值、IPv4-mapped IPv6 和普通 IPv6：

func TestAddressKeyBoundaries(t *testing.T) {
    a := netip.MustParseAddr("192.0.2.10")
    b := netip.MustParseAddr("::ffff:192.0.2.10")

    if a == b {
        t.Fatal("mapped IPv6 must not equal IPv4 before Unmap")
    }
    if a != b.Unmap() {
        t.Fatal("Unmap should make the business identity equal")
    }

    var zero netip.Addr
    if zero.IsValid() {
        t.Fatal("zero Addr must be rejected")
    }
}

运行 go test ./... 后，再用一组真实配置文件做一次加载验收：错误地址应在启动阶段被拒绝，合法地址应能在一次查找中命中。这样比单纯比较字符串更能保证迁移没有悄悄改变授权范围。

几个不适合直接替换的场景

• 如果下游 API 明确要求 net.IP，可以在边界转换，不必为了统一类型一次性改完所有模块。
• 如果日志需要保留用户输入原文，应该同时保存原文和规范化后的 Addr，不要用格式化结果取代审计字段。
• 如果地址来自代理头或用户输入，netip.ParseAddr 只负责语法解析，不会替你判断信任链、代理层级和授权策略。

相关问题

netip.Addr 可以直接作为 map 的 key 吗？

可以。它是可比较的值类型，适合用于 map[netip.Addr]T。使用前仍要处理无效零值。

为什么 0.0.0.0 和 Addr{} 不能混为一谈？

Addr{} 表示没有有效地址，0.0.0.0 是有效的 IPv4 unspecified 地址，业务含义不同。

什么时候调用 Unmap？

只有在业务希望把 IPv4 和 IPv4-mapped IPv6 视作同一身份时调用；需要保留地址族信息时不要调用。

结语

把 IP 放入 map 的真正难点不是选哪一种容器，而是先定义地址身份。netip.Addr 解决了可比较、不可变和规范表示这几个基础问题；零值有效性与 IPv4 映射则仍然要由业务入口明确。把这些规则集中在一次转换和一组边界测试里，后续的白名单、缓存和连接统计都会简单很多。