Go net/netip.Prefix.Overlaps 如何判断网段相交：地址族与前缀边界

做网段白名单时，最容易写错的不是 CIDR 解析，而是“相交”这个判断：10.20.0.0/16 和 10.20.3.0/24 明显有共同地址，但 IPv4 与 IPv6、零值前缀、IPv4 映射 IPv6 并不属于同一条规则。Go 的 net/netip.Prefix.Overlaps 已经把这些边界收进标准库，关键是先看清它判断的对象。

Prefix.Overlaps 判断两个前缀是否包含共同 IP；相同地址族的嵌套网段和 /0 可以相交，不同地址族、无效前缀和零值前缀直接返回 false。

先用一个网段重叠检查器跑通最小路径

把判断封装成小函数，调用方只接收两个合法的 netip.Prefix。ParsePrefix 会把文本转换为前缀，随后 Prefix.Overlaps 只负责回答集合是否相交。

package main

import (
    "fmt"
    "net/netip"
)

func overlaps(aText, bText string) (bool, error) {
    a, err := netip.ParsePrefix(aText)
    if err != nil {
        return false, fmt.Errorf("parse first prefix: %w", err)
    }
    b, err := netip.ParsePrefix(bText)
    if err != nil {
        return false, fmt.Errorf("parse second prefix: %w", err)
    }
    return a.Overlaps(b), nil
}

func main() {
    got, err := overlaps("10.20.0.0/16", "10.20.3.0/24")
    fmt.Println(got, err) // true 
}

这里的成功状态不是“两个字符串前缀相同”，而是两个集合至少共享一个 IP。10.20.3.0/24 被包含在 10.20.0.0/16 中，所以结果为 true。如果输入无法解析，函数在调用 Overlaps 前返回错误，避免把配置问题误报成“不相交”。

Prefix.Overlaps 实际比较的是地址集合

可以把一个前缀看成一组地址。10.20.0.0/16 包含从 10.20.0.0 到 10.20.255.255 的 IPv4 地址，10.20.3.0/24 是它里面更窄的一段；二者有交集。

相邻网段则不同：10.20.0.0/24 与 10.20.1.0/24 没有共同 IP，虽然它们首地址连续，Overlaps 仍返回 false。如果业务还需要判断“相邻”，应另写相邻规则，不要把 Overlaps 当成合并判断。

地址族和无效前缀是两个硬边界

IPv4 与 IPv6 属于不同地址族，即使它们的 CIDR 位数看起来相同，也不会相交。netip 还把 IPv4-mapped IPv6 当作 IPv6 地址处理，因此它不能绕过地址族隔离。

tests := []struct {
    name string
    a, b netip.Prefix
    want bool
}{
    {"nested", netip.MustParsePrefix("10.20.0.0/16"), netip.MustParsePrefix("10.20.3.0/24"), true},
    {"different family", netip.MustParsePrefix("10.20.0.0/16"), netip.MustParsePrefix("2001:db8::/32"), false},
    {"zero prefix", netip.Prefix{}, netip.MustParsePrefix("10.20.0.0/16"), false},
}

for _, tc := range tests {
    if got := tc.a.Overlaps(tc.b); got != tc.want {
        panic(tc.name)
    }
}

生产配置不要用 MustParsePrefix 处理外部输入，它适合固定在测试代码里的常量。服务启动时读取白名单，应保留 ParsePrefix 的错误上下文；对零值前缀则明确记录为配置缺失，而不是把它当作“允许所有地址”。

把边界测试放在白名单加载处

如果网段来自环境变量或数据库，建议在加载阶段完成解析和规范化，后续请求只遍历合法的 []netip.Prefix。下面的检查覆盖嵌套、相邻、跨族和非法前缀四类最容易混淆的输入。

func allowed(ip netip.Addr, prefixes []netip.Prefix) bool {
    for _, prefix := range prefixes {
        if prefix.Contains(ip) {
            return true
        }
    }
    return false
}

func hasOverlap(candidate netip.Prefix, existing []netip.Prefix) bool {
    for _, prefix := range existing {
        if candidate.Overlaps(prefix) {
            return true
        }
    }
    return false
}

Overlaps 适合在新增白名单前检查“是否已经覆盖”，Contains 适合在请求到达时判断某个 IP 是否被允许。两者都不替代输入校验，也不负责合并前缀；这三个职责分开，后续审计日志才容易解释。

常见问题

两个相邻的 CIDR 为什么不是 Overlaps？

相邻只表示一个网段的末地址紧接着另一个网段的首地址，二者没有共同 IP，所以 Overlaps 返回 false。

IPv4-mapped IPv6 能和 IPv4 网段相交吗？

不能。官方实现按地址族判断，IPv4-mapped IPv6 仍按 IPv6 掩码处理，不会与 IPv4 前缀相交。

可以用零值 Prefix 表示全部地址吗？

不可以。零值前缀是无效值，Overlaps 会返回 false。全部 IPv4 地址应显式使用 0.0.0.0/0，IPv6 则使用 ::/0。

最后的验收清单

• 输入来自外部时使用 ParsePrefix 并检查错误。
• 新增网段前用 Overlaps 检查已有覆盖关系。
• 请求 IP 判断使用 Contains，不要把它和网段相交混用。
• 测试显式覆盖嵌套、相邻、跨地址族、零值和 /0。