Go netip.Prefix 如何判断网段包含关系：边界地址、掩码与规范化

服务端收到一条 CIDR 配置时，真正要判断的通常不是“这是不是一个像样的 IP”，而是请求地址是否落在允许网段里。Go 的 netip.Prefix 把地址和前缀长度放在一个小值类型中，配合 Contains、Masked 就能把这件事写得短而清楚。

先把 CIDR 变成可验证的 Prefix

配置文件里的 10.20.30.7/24 可能带着主机位。它可以被解析，但作为访问控制规则时，通常应该明确保存成网络地址 10.20.30.0/24。解析和规范化分成两步，问题会更容易定位。

package main

import (
    "fmt"
    "net/netip"
)

func parseNetwork(raw string) (netip.Prefix, error) {
    prefix, err := netip.ParsePrefix(raw)
    if err != nil {
        return netip.Prefix{}, fmt.Errorf("invalid network %q: %w", raw, err)
    }
    return prefix.Masked(), nil
}

func main() {
    network, err := parseNetwork("10.20.30.7/24")
    if err != nil {
        panic(err)
    }
    fmt.Println(network) // 10.20.30.0/24
}

Masked 不会改变前缀长度，只会清掉地址中超出前缀长度的主机位。这样日志、缓存键和规则比较都有一个稳定的文本表示。

最小配方：Contains 判断地址是否在网段内

拿到一个待校验地址后，直接调用 Contains。它的参数是 netip.Addr，所以先用 ParseAddr 处理输入，不要把解析失败的空值继续传下去。

func allowed(rawIP, rawCIDR string) (bool, error) {
    addr, err := netip.ParseAddr(rawIP)
    if err != nil {
        return false, fmt.Errorf("invalid client ip %q: %w", rawIP, err)
    }

    prefix, err := netip.ParsePrefix(rawCIDR)
    if err != nil {
        return false, fmt.Errorf("invalid allowlist prefix %q: %w", rawCIDR, err)
    }

    return prefix.Masked().Contains(addr), nil
}

例如 10.20.30.99 属于 10.20.30.7/24 规范化后的网段，而 10.20.31.1 不属于。/32 则只包含一个 IPv4 地址；IPv6 的 /128 也是同样的单地址边界。

两个变体：检查网段重叠与严格配置

用 Overlaps 检查两条规则是否冲突

如果系统允许配置多条网段，Contains 只适合“地址对网段”的判断。两条 CIDR 是否有交集，应该使用 Overlaps，并且先分别规范化。

func overlaps(left, right string) (bool, error) {
    a, err := netip.ParsePrefix(left)
    if err != nil {
        return false, err
    }
    b, err := netip.ParsePrefix(right)
    if err != nil {
        return false, err
    }
    return a.Masked().Overlaps(b.Masked()), nil
}

要求配置必须已经是网络地址

有些团队希望拒绝 10.20.30.7/24 这种带主机位的输入，避免用户误以为规则只覆盖一个地址。比较原始前缀与规范化结果即可：

prefix, err := netip.ParsePrefix(raw)
if err != nil {
    return err
}
if prefix != prefix.Masked() {
    return fmt.Errorf("prefix %q contains host bits", raw)
}

如果产品语义是“尽量接受并规范化”，就保留前面的 Masked；如果配置需要审计和人工复核，拒绝主机位往往更稳。

IPv4、IPv6 和格式错误别混在一起处理

Prefix 会保留地址族。192.0.2.0/24 不能拿去匹配 2001:db8::1，这不是“没命中”之外需要另写位运算的场景，调用前把地址族写进错误信息即可。

func check(rawIP, rawCIDR string) error {
    addr, err := netip.ParseAddr(rawIP)
    if err != nil {
        return fmt.Errorf("client address: %w", err)
    }
    prefix, err := netip.ParsePrefix(rawCIDR)
    if err != nil {
        return fmt.Errorf("allowlist: %w", err)
    }
    prefix = prefix.Masked()
    if addr.Is4() != prefix.Addr().Is4() {
        return fmt.Errorf("address family mismatch: ip=%s prefix=%s", addr, prefix)
    }
    if !prefix.Contains(addr) {
        return fmt.Errorf("address %s is outside %s", addr, prefix)
    }
    return nil
}

常见误区与验收清单

• 不要只比较 prefix.Addr()：同一网段中绝大多数地址都不会等于网络起始地址。
• 不要忽略 ParseAddr 和 ParsePrefix 的错误；空的 Addr 不代表合法输入。
• 保存规则前先决定“规范化”还是“拒绝主机位”，两者都是合理策略，但不能默默混用。
• 测试至少覆盖网络起始地址、最后一个地址、网段外地址、/32、/128、IPv4/IPv6 混用和非法 CIDR。

一段可直接放进配置校验的完整示例

package main

import (
    "fmt"
    "net/netip"
)

func inNetwork(rawIP, rawCIDR string) (bool, error) {
    ip, err := netip.ParseAddr(rawIP)
    if err != nil {
        return false, fmt.Errorf("parse ip: %w", err)
    }
    network, err := netip.ParsePrefix(rawCIDR)
    if err != nil {
        return false, fmt.Errorf("parse cidr: %w", err)
    }
    network = network.Masked()
    if ip.Is4() != network.Addr().Is4() {
        return false, fmt.Errorf("ip family differs from cidr")
    }
    return network.Contains(ip), nil
}

func main() {
    ok, err := inNetwork("10.20.30.99", "10.20.30.7/24")
    fmt.Println(ok, err) // true 
}

这套写法把解析、规范化、地址族核对和包含关系分开，后续换成配置热加载或 HTTP 中间件时仍然容易测试。真正需要扩展时，优先给 inNetwork 增加表驱动测试，而不是重新实现一套 CIDR 位运算。

相关问题

Prefix.Contains 能判断两个网段吗？

不能直接把另一个 Prefix 传给它；判断两个网段是否有交集用 Overlaps，判断一个网段是否完全包含另一个网段时可先比较地址族、前缀长度和对方网络起始地址。

为什么输出的 Prefix 地址和输入不一样？

因为输入可能含有主机位。调用 Masked 后，主机位被清零，得到的是该前缀的规范网络地址。

把 CIDR 当作值类型处理，先解析、再规范化，最后用标准库语义判断，通常比手写掩码更容易审查，也更不容易在 IPv6 或边界地址上留下隐蔽错误。