Go netip.Prefix Overlaps 怎样判断两个网段是否重叠

在访问控制、路由聚合或 IP 地址池配置里，我经常遇到一个看似简单的问题：两个 CIDR 网段到底有没有交集？如果只是拿字符串比较，或者把 IPv4 和 IPv6 都塞进同一套整数逻辑，结果很容易在边界处失真。Go 的 net/netip 已经把这个判断收进了 Prefix.Overlaps：它回答的是两个前缀是否包含共同的 IP 地址。

处理两个网段时，先用 ParsePrefix 保留输入错误，再用 Masked 得到规范前缀，最后调用 Overlaps 判断交集；不同地址族或零值前缀会得到 false，不能把它当成“输入一定有效”。

官方参考：https://pkg.go.dev/net/netip#Prefix.Overlaps

先确认 Overlaps 判断的对象

netip.Prefix 表示一个 IP 地址前缀，也就是 CIDR 网段。比如 10.20.0.0/16 覆盖的地址空间包含 10.20.12.0/24，两者有共同地址，Overlaps 应该返回 true。而 10.20.0.0/24 与 10.20.1.0/24 没有共同地址，结果就是 false。

这个方法判断的是“网段与网段的交集”，不是“某个 IP 是否属于网段”。后者应该使用 Prefix.Contains。先把两个概念分开，后面的封装才不会把路由规则和单地址规则混在一起。

先解析并规范化 CIDR

外部配置通常是字符串，第一步不要直接构造零值 Prefix。ParsePrefix 会返回解析错误，调用方可以据此拒绝非法 CIDR。官方文档也说明，IPv6 区域标识不能出现在前缀中；输入类似带网卡区域的 IPv6 前缀时，应把它当成无效配置处理。

package main

import (
    "fmt"
    "net/netip"
)

// parseNetwork 解析配置里的 CIDR，并返回规范化后的网络前缀。
func parseNetwork(raw string) (netip.Prefix, error) {
    // 先保留解析错误，避免非法输入被静默转换成零值前缀。
    prefix, err := netip.ParsePrefix(raw)
    if err != nil {
        return netip.Prefix{}, fmt.Errorf("解析网段 %q: %w", raw, err)
    }

    // 清掉地址中的主机位，便于日志、缓存键和后续比较保持稳定。
    return prefix.Masked(), nil
}

func main() {
    // 这个示例只展示解析边界，不把输出当成线上运行证据。
    prefix, err := parseNetwork("10.20.12.7/24")
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(prefix)
}

ParsePrefix("10.20.12.7/24") 得到的是带有原始地址信息的前缀，Masked() 才会把主机位清零，得到更适合展示和持久化的 10.20.12.0/24。如果输入来自可信的硬编码测试，也可以使用 MustParsePrefix，但配置文件、请求参数和数据库字段仍应优先使用返回错误的版本。

用 Prefix.Overlaps 判断网段交集

比较函数应该同时返回布尔结果和解析错误。这样，false, nil 才表示“两个有效前缀没有共同地址”，而 false, err 表示输入根本没有进入比较阶段。

// prefixesOverlap 比较两个 CIDR 是否共享至少一个 IP 地址。
func prefixesOverlap(left, right string) (bool, error) {
    // 两边分别解析，任何一边非法都立即返回具体错误。
    leftPrefix, err := parseNetwork(left)
    if err != nil {
        return false, err
    }
    rightPrefix, err := parseNetwork(right)
    if err != nil {
        return false, err
    }

    // Overlaps 负责判断地址空间交集，不需要手写起止地址算法。
    return leftPrefix.Overlaps(rightPrefix), nil
}

func compareExamples() {
    examples := []struct {
        left  string
        right string
    }{
        {left: "10.20.0.0/16", right: "10.20.12.0/24"},
        {left: "10.20.0.0/24", right: "10.20.1.0/24"},
        {left: "2001:db8:1::/48", right: "2001:db8:1:10::/64"},
    }

    for _, example := range examples {
        overlap, err := prefixesOverlap(example.left, example.right)
        if err != nil {
            // 解析失败要单独记录，不能把它和“不重叠”合并。
            fmt.Printf("%s / %s: error: %v\n", example.left, example.right, err)
            continue
        }
        fmt.Printf("%s / %s: overlap=%t\n", example.left, example.right, overlap)
    }
}

这段封装的重点是错误语义：前两个 IPv4 示例分别对应 true 和 false，IPv6 嵌套前缀对应 true。如果右侧写成非法字符串，函数返回错误，而不是把一个没有意义的零值前缀拿去比较。

处理 IPv4、IPv6 与零值边界

Overlaps 对地址族有明确边界：IPv4 前缀与 IPv6 前缀不可能共享地址，因此返回 false。IPv4-mapped IPv6 地址仍按 IPv6 处理，也不能因为文本里出现了 IPv4 形式就当作普通 IPv4。比较前如果业务允许混合输入，可以先在业务层把地址族不一致记录为“无交集”，而不是继续做自定义位运算。

另外，零值 netip.Prefix{} 不代表 0.0.0.0/0 或 ::/0。解析失败时如果只留下一个零值，再调用 Overlaps，得到的 false 很容易掩盖真正的配置错误。因此建议保持上面的错误返回约定，并在接收结构化配置时额外检查 prefix.IsValid()。

把判断放进路由或访问规则

实际项目中可以把比较放在配置加载、规则去重或变更预检阶段。常见的判断表如下：

如果规则要求“完全不重叠”，就对每一对有效前缀调用 Overlaps；如果规则要求“新网段必须包含在旧网段内”，则应该改成比较 Contains 或进一步比较前缀长度，不能仅凭 Overlaps == true 下结论。

常见问题

两个前缀的地址族不同，为什么不报错？

这是正常的布尔判断边界。Overlaps 用 false 表示它们没有共同地址；如果业务需要把“地址族不一致”作为配置错误，应在调用前比较 Addr().BitLen() 并单独返回业务错误。

为什么不直接把 CIDR 转成起止整数比较？

手写起止算法要同时处理 IPv4、IPv6、前缀长度、规范化和无效输入。netip.Prefix 已经提供了地址族与前缀语义，直接使用 Overlaps 更容易保持边界一致。

什么时候必须调用 Masked？

当你需要稳定的日志、去重键、序列化结果或后续规则比较时，建议先调用 Masked。只关心 Overlaps 的真假时，方法本身仍然可以完成比较，但规范化能减少同一网络的多种文本表现。

总结一下：把 CIDR 字符串先解析成 netip.Prefix，对要持久化或展示的值调用 Masked，用 Overlaps 判断网段交集，用错误返回区分非法输入，用 Contains 处理单地址归属。这样，IPv4、IPv6、零值和主机位这些容易混淆的边界都会落在清晰的 API 语义上。