Go netip.Prefix.Contains 怎样判断 IP 是否属于指定网段

在白名单、路由前置判断或服务来源分类中，常见问题是：拿到一个 CIDR 网段和一个 IP 地址，怎样可靠判断后者是否属于前者？Go 标准库的 net/netip 已经提供了清晰的组合：先用 netip.ParsePrefix 解析网段，再调用 Prefix.Contains。不要手工把 IP 拆成整数，也不要只比较字符串前缀。

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

判断链可以固定为“解析输入 → 检查错误 → 判断地址族 → Contains 返回布尔值”。Prefix.Contains 只表示网络是否包含地址，不替你处理输入格式、访问控制策略或日志审计。

先把 CIDR 和候选 IP 变成 netip 类型

Prefix.Contains 的参数是 netip.Addr，不是字符串。因此入口处应同时解析前缀和候选地址，并把解析失败当成不匹配或输入错误处理。下面的函数返回“是否属于网段”和解析错误，调用方可以决定是拒绝请求还是提示配置问题。

package main

import (
    "fmt"
    "net/netip"
)

// inPrefix 只负责解析和归属判断，不把非法输入误当成匹配。
func inPrefix(cidrText, ipText string) (bool, error) {
    prefix, err := netip.ParsePrefix(cidrText)
    if err != nil {
        return false, fmt.Errorf("解析网段 %q: %w", cidrText, err)
    }

    ip, err := netip.ParseAddr(ipText)
    if err != nil {
        return false, fmt.Errorf("解析 IP %q: %w", ipText, err)
    }

    // Contains 的返回值就是“这个网络是否包含该地址”。
    return prefix.Contains(ip), nil
}

func main() {
    ok, err := inPrefix("192.0.2.0/24", "192.0.2.42")
    fmt.Println(ok, err) // true 
}

成功路径只关心一个布尔值，错误路径则保留了具体输入和原始错误。生产代码中可以把错误映射成统一的配置错误，但不要为了“让程序继续”忽略 ParsePrefix 或 ParseAddr 的错误。

IPv4 和 IPv6 要按地址族理解结果

Contains 不是简单的“位数比较”。IPv4 地址不会匹配 IPv6 前缀，IPv4-mapped IPv6 地址也不会匹配普通 IPv4 前缀。因此，配置和请求输入最好在同一地址族内比较。

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    v4Prefix := netip.MustParsePrefix("192.0.2.0/24")
    v6Prefix := netip.MustParsePrefix("2001:db8::/32")

    cases := []struct {
        name string
        p    netip.Prefix
        ip   netip.Addr
    }{
        {"IPv4 命中", v4Prefix, netip.MustParseAddr("192.0.2.42")},
        {"IPv4 越界", v4Prefix, netip.MustParseAddr("198.51.100.8")},
        {"IPv6 命中", v6Prefix, netip.MustParseAddr("2001:db8::42")},
        {"地址族不同", v4Prefix, netip.MustParseAddr("2001:db8::42")},
    }

    for _, item := range cases {
        // 每个样例复用同一规则，便于扩展白名单或路由表。
        fmt.Printf("%s: %v\n", item.name, item.p.Contains(item.ip))
    }
}

这里的“地址族不同”应当得到 false，而不是先把 IPv6 转成字符串再做模糊比较。若业务真的允许 IPv4-mapped IPv6 输入，应在边界层明确决定是否调用 Addr.Unmap，并把这个策略写进测试；不要让不同调用方各自猜测。

IPv6 zone、零值地址和前缀规范化不能混为一谈

官方文档明确说明：带 IPv6 zone 的地址不会匹配前缀，因为前缀会去掉 zone；零值 Addr 也不会匹配任何前缀。这些规则很适合在输入层形成明确的拒绝分支。

func safeContains(prefix netip.Prefix, ip netip.Addr) bool {
    // 先挡住未初始化地址，避免它和业务中的“未填写”混在一起。
    if !ip.IsValid() {
        return false
    }
    // zone 通常表示接口作用域；本例的 CIDR 白名单不接受它。
    if ip.Zone() != "" {
        return false
    }
    return prefix.Contains(ip)
}

另一个容易忽略的点是前缀是否为规范形式。配置中的 192.0.2.42/24 仍然表达一个 /24 网段，但展示、比较、缓存键或日志记录时，建议先调用 Masked 得到规范化前缀。规范化只解决表示一致性，不会替代 Contains 的地址族判断。

func canonicalPrefix(text string) (netip.Prefix, error) {
    prefix, err := netip.ParsePrefix(text)
    if err != nil {
        return netip.Prefix{}, err
    }
    // Masked 让日志和缓存键统一使用网络地址，而不是主机位输入。
    return prefix.Masked(), nil
}

把判断放进白名单或路由前置流程

实际工程中，可以在启动时解析并规范化所有网段，收到请求时只解析来源 IP，再逐条调用 Contains。网段配置错误应在启动阶段暴露；请求中的非法 IP 则应走明确的 400、拒绝或审计分支。不要在每次请求里悄悄修正配置文本，也不要把 Addr.IsPrivate 当成网段白名单，它们解决的不是同一个问题。

最后用边界用例固定行为

最少覆盖命中、越界、地址族不匹配、非法文本、零值和 zone。测试的重点不是重复标准库实现，而是锁定你自己的输入策略：哪些错误返回给调用方，哪些输入进入审计，哪些地址族可以被统一。

func ExamplePrefixContains() {
    prefix := netip.MustParsePrefix("192.0.2.0/24")

    fmt.Println(prefix.Contains(netip.MustParseAddr("192.0.2.1")))
    fmt.Println(prefix.Contains(netip.MustParseAddr("192.0.3.1")))
    // 输出顺序固定为 true、false，覆盖命中与越界两个核心边界。
    // Output:
    // true
    // false
}

总结一下：先解析为 Prefix 和 Addr，再使用 Prefix.Contains；不要忽略解析错误、地址族、zone 和规范化语义。这样写出来的网段判断短小，但边界是可读、可测试、可审查的。

相关问题

• 前缀地址带主机位时要怎么办？用 Masked 得到规范形式，再用于日志、比较或缓存键。
• 为什么 IPv4-mapped IPv6 没有命中 IPv4 前缀？它仍属于 IPv6 表示，是否先 Unmap 应由业务策略决定。
• 带 zone 的 IPv6 地址能不能判断？可以先按业务规则去掉或拒绝 zone，但不要期待普通 Prefix 自动把它当作同一地址。
• 只有一个 IP 地址时还需要 Contains 吗？可以用 /32 或 /128 前缀表达单地址范围，仍保持统一的网段判断接口。