Go netip 地址怎么转换成可比较的映射键

Go 的 netip.Addr 不需要再转成字符串才能作为映射键：它本身就是不可变、可比较的值类型。实际做法是先用 netip.ParseAddr 解析输入，再根据业务是否把 IPv4 和 IPv4-mapped IPv6 视为同一个地址决定是否调用 Unmap，最后直接使用 map[netip.Addr]V。

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

先把输入解析成 netip.Addr

netip.ParseAddr 接受 IPv4、IPv6 以及带作用域 zone 的 IPv6 文本，并返回 (Addr, error)。因此外部字符串不能直接进缓存，必须让错误停在入口处；这样 map 中不会混入拼写不同但无法解释的键。

package ipkey

import "net/netip"

// ParseKey 只把语法有效的地址交给后续映射逻辑。
func ParseKey(raw string) (netip.Addr, error) {
    addr, err := netip.ParseAddr(raw)
    if err != nil {
        // 保留原始错误，调用方可以决定记录、丢弃或返回请求错误。
        return netip.Addr{}, err
    }
    return addr, nil
}

不要把 Addr.String() 当作“转换成可比较键”的必要步骤。字符串会引入格式和分配问题，而 Addr 的比较由类型自身完成；只有需要日志、JSON 或协议字段时才转回文本。

先定义地址的规范化等价关系

最容易出现“同一地址命中两次”的情况，是 IPv4-mapped IPv6。netip 把 ::ffff:192.0.2.10 视为 IPv6 形式；如果业务把它和 192.0.2.10 视为同一个端点，就应在生成键时统一调用 Unmap。如果系统必须保留原始地址族，则不要调用它。

// CanonicalKey 按“IPv4-mapped 与 IPv4 等价”的业务规则生成键。
func CanonicalKey(raw string) (netip.Addr, error) {
    addr, err := netip.ParseAddr(raw)
    if err != nil {
        return netip.Addr{}, err
    }

    // Unmap 对普通 IPv4 和普通 IPv6 不改值，只消除 IPv4-mapped 差异。
    return addr.Unmap(), nil
}

zone 则是另一个维度：fe80::1%eth0 和 fe80::1%eth1 不是同一个链路作用域。只有在业务已经确定 zone 不影响身份时，才用 WithZone("") 去掉它；不能为了“看起来统一”无条件删除。

直接用 netip.Addr 建立类型安全的映射

键规范化完成后，声明 map[netip.Addr]V 即可。读取路径必须复用同一套规范化函数，否则写入和查询会分别采用不同等价关系，表现为“明明是同一个 IP 却查不到”。

type Counter struct {
    Hits uint64
}

// Index 保存按地址聚合的计数；写入和查询共用 CanonicalKey。
type Index struct {
    values map[netip.Addr]Counter
}

func (idx *Index) Add(raw string) error {
    key, err := CanonicalKey(raw)
    if err != nil {
        return err
    }
    if idx.values == nil {
        // 延迟初始化，避免零值 Index 在第一次写入时发生 panic。
        idx.values = make(map[netip.Addr]Counter)
    }
    item := idx.values[key]
    item.Hits++
    idx.values[key] = item
    return nil
}

若并发读写这个 map，还需要由互斥锁或其他并发容器保护；Addr 可比较不等于 map 自动并发安全。若键还包含端口，优先解析成 netip.AddrPort，不要手工用冒号拼接 IPv6。

零值、非法地址和端口要分开处理

netip.Addr{} 是零值且无效，0.0.0.0 与 :: 却是有效的未指定地址。调用 IsValid 可以判断 Addr 是否已初始化，不能把未指定地址误当成解析失败。端口场景使用 netip.ParseAddrPort，它要求地址和端口都是数字，也不会替你做 DNS 解析。

常见问题

为什么不用 string 做 IP map 键？

string 当然可以做键，但同一地址可能出现 IPv4-mapped、IPv6 压缩和 zone 等不同表示。使用 Addr 能让解析、比较和规范化边界集中在类型层。

Unmap 是不是所有项目都必须调用？

不是。只有当业务定义 IPv4 与 IPv4-mapped IPv6 为同一个身份时才调用；保留地址族的路由或诊断系统应继续使用原值。

Addr 能作为 map 键，为什么还要检查 IsValid？

“可比较”只说明类型满足 Go map 键要求，不代表每个值都有业务意义。零值可以放进 map，但通常应在入口处拒绝，避免把缺失地址聚合到一个普通键上。

因此，可靠方案不是把 IP 文本机械转换成另一种字符串，而是：ParseAddr 负责输入边界，Unmap 和 zone 策略负责定义等价关系，最后直接用 netip.Addr 作为 map 键。只要写入与查询共享同一规范化函数，地址映射就能保持稳定。