Go netipIP 前缀 contains 判断结果异常怎么办

netip.Prefix.Contains 判断异常时，优先不要改位运算。它的返回值通常是在提醒输入的语义不一致：前缀和地址不是同一地址族、地址是 IPv4-mapped IPv6、地址带 IPv6 zone、地址是零值，或者前缀本身无效。先把这些状态打印出来，再决定是否需要 Unmap、去掉 zone 或调用 Masked。

先确认 Contains 比较的到底是什么

Prefix 表示一个 CIDR 网络，前缀的前 Bits() 位固定，其余位允许变化。Contains 做的是“这个网络是否包含这个 Addr”，不是比较两个字符串是否长得相似，也不是把 IPv4 和 IPv4-mapped IPv6 自动转换成同一类型。

官方实现先检查前缀有效性和地址的 zone，再比较地址位数；地址族不相同、任一地址无效或输入带 zone 时直接返回 false。因此排查的第一步应该是检查输入状态，而不是扩大 CIDR。

先检查前缀和地址是否有效

下面的排障函数只打印与 Contains 相关的状态。它不会把输入悄悄转换成另一个地址，因此适合放在单元测试或问题复现代码里。

package main

import (
    "fmt"
    "net/netip"
)

func inspect(prefixText, addrText string) {
    // ParsePrefix 和 ParseAddr 都返回错误，避免用 MustParse 把输入问题变成 panic。
    prefix, prefixErr := netip.ParsePrefix(prefixText)
    addr, addrErr := netip.ParseAddr(addrText)
    if prefixErr != nil || addrErr != nil {
        fmt.Printf("prefixErr=%v addrErr=%v\n", prefixErr, addrErr)
        return
    }

    // Bits、Addr 和 IsValid 能直接暴露前缀是否可用于 Contains。
    fmt.Printf("prefix=%s valid=%v bits=%d family=%d\n",
        prefix, prefix.IsValid(), prefix.Bits(), prefix.Addr().BitLen())
    fmt.Printf("addr=%s valid=%v bitlen=%d zone=%q contains=%v\n",
        addr, addr.IsValid(), addr.BitLen(), addr.Zone(), prefix.Contains(addr))
}

func main() {
    inspect("192.168.0.0/24", "192.168.0.42")
    inspect("2001:db8::/32", "192.168.0.42")
}

第一组输入的地址位数都是 32，应该命中；第二组把 IPv4 地址交给 IPv6 前缀，返回 false 是设计行为。注意零值地址的 IsValid() 为 false，不要只看它格式化后的空字符串。

IPv4-mapped IPv6 为什么不会命中 IPv4 前缀

下面两个地址在很多网络场景里表达了同一个 IPv4 数值，但在 netip 中它们仍是不同的地址表示：192.0.2.7 是 IPv4，::ffff:192.0.2.7 是 IPv4-mapped IPv6。官方文档明确说明，mapped IPv6 不会匹配 IPv4 前缀。

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    // 让前缀和候选地址都先按文本解析，便于观察地址族差异。
    prefix := netip.MustParsePrefix("192.0.2.0/24")
    ipv4 := netip.MustParseAddr("192.0.2.7")
    mapped := netip.MustParseAddr("::ffff:192.0.2.7")

    fmt.Println(prefix.Contains(ipv4))          // true：IPv4 对 IPv4
    fmt.Println(prefix.Contains(mapped))        // false：IPv6 对 IPv4
    fmt.Println(prefix.Contains(mapped.Unmap())) // true：显式转换后再判断
}

如果业务协议规定所有候选地址都按 IPv4 处理，可以在明确记录这一规则后调用 Unmap()。不要无条件转换，因为真正的 IPv6 地址不能因此变成 IPv4，地址族本身可能是路由策略的一部分。

IPv6 zone 会让看起来正确的地址返回 false

链路本地 IPv6 地址可能带接口 zone，例如 fe80::1%en0。前缀不允许带 zone，而 Contains 对带 zone 的候选地址返回 false，这是为了避免把接口范围信息静默丢掉。

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    // Prefix 不携带 zone；带 zone 的 Addr 需要先做业务上明确的清理。
    prefix := netip.MustParsePrefix("fe80::/10")
    zoned := netip.MustParseAddr("fe80::1%en0")

    fmt.Printf("zoned=%s zone=%q contains=%v\n",
        zoned, zoned.Zone(), prefix.Contains(zoned))
    fmt.Printf("withoutZone=%s contains=%v\n",
        zoned.WithZone(""), prefix.Contains(zoned.WithZone("")))
}

去掉 zone 只能在业务已经确认“接口范围不参与这次网段判断”时进行。若要判断具体链路上的可达性，应该保留 zone 并把接口选择交给后续网络操作，而不是为得到 true 盲目清理。

PrefixFrom 保留主机位，Masked 才生成规范前缀

另一个常见误判来自构造前缀的方式。Addr.Prefix 会屏蔽主机位，而 PrefixFrom 明确不会屏蔽。于是 PrefixFrom(192.168.1.99, 24) 的字符串可能保留为 192.168.1.99/24，但它依然表示前 24 位用于匹配。需要规范化显示、序列化或做稳定键时，再调用 Masked()。

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    addr := netip.MustParseAddr("192.168.1.99")

    // PrefixFrom 只记录地址和位数，不会自动清零主机位。
    raw := netip.PrefixFrom(addr, 24)
    // Masked 生成规范 CIDR，适合展示、比较和持久化。
    canonical := raw.Masked()

    candidate := netip.MustParseAddr("192.168.1.7")
    fmt.Printf("raw=%s masked=%s contains=%v\n",
        raw, canonical, raw.Contains(candidate))
}

这里 raw.Contains(candidate) 仍然依据前 24 位判断，并不会因为地址里保留了主机位就自动失效。真正需要关注的是前缀是否有效、地址族是否一致，以及输入是否带 zone。

把排障结论固化成测试表

网络地址边界适合用表驱动测试固定下来。测试名称应说明“为什么命中或不命中”，这样以后有人把 IPv4-mapped IPv6 或带 zone 的地址接入时，失败信息会比单个布尔值更容易理解。

package netipcheck

import (
    "net/netip"
    "testing"
)

func TestPrefixContainsBoundaries(t *testing.T) {
    cases := []struct {
        name   string
        prefix string
        addr   string
        want   bool
    }{
        {"same IPv4 family", "192.168.0.0/24", "192.168.0.7", true},
        {"different family", "2001:db8::/32", "192.168.0.7", false},
        {"mapped IPv6", "192.0.2.0/24", "::ffff:192.0.2.7", false},
        {"zoned IPv6", "fe80::/10", "fe80::1%en0", false},
    }

    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            // 测试数据是固定字符串，解析错误说明用例本身不完整。
            prefix, err := netip.ParsePrefix(tc.prefix)
            if err != nil {
                t.Fatal(err)
            }
            addr, err := netip.ParseAddr(tc.addr)
            if err != nil {
                t.Fatal(err)
            }
            if got := prefix.Contains(addr); got != tc.want {
                t.Fatalf("Contains(%s)=%v, want %v", addr, got, tc.want)
            }
        })
    }
}

常见问题

为什么 netip.Prefix.Contains 不能把 IPv4-mapped IPv6 当成 IPv4？

因为 netip.Addr 保留地址族信息，mapped IPv6 仍然是 IPv6。只有在协议明确把它视为 IPv4 时，才应显式调用 Unmap()。

PrefixFrom 得到的地址没有归零，是不是前缀错误？

不一定。PrefixFrom 的契约就是保留主机位；需要规范 CIDR 时调用 Masked()，Contains 仍会按前缀位判断。

为什么给 IPv6 地址加了 zone 后 Contains 就变成 false？

Prefix 不携带 zone，Contains 不会静默丢弃候选地址的接口范围，所以带 zone 的地址直接不匹配。只有业务确认 zone 无关时才清理它。

零值地址能否用在 /0 前缀判断中？

不能。零值 netip.Addr{} 不是合法 IP，即使前缀是 0.0.0.0/0 或 ::/0，也不会命中。

排查 Contains 的顺序可以固定为：解析错误 → IsValid → 地址族和 BitLen → Unmap 或 zone 策略 → Masked 展示规范化。这样得到的修复是针对输入契约，而不是靠放宽网段掩盖数据问题。