Go net/netip ParsePrefix 如何判断地址是否属于网段：Bits、Masked 与 Contains

做 IP 白名单时，真正容易写错的不是字符串比较，而是把“输入的网段”与“网段中的地址”混成了一件事。Go 的 net/netip 已经把这条路径拆成了三个动作：ParsePrefix 解析 CIDR，Masked 把地址归一到网络边界，Prefix.Contains 判断某个地址是否落在这个前缀里。

判断地址是否属于网段时，先用 ParsePrefix 得到 Prefix，需要展示或比较规范网络地址时调用 Masked，真正做归属判断直接使用 Prefix.Contains；不要拿 Prefix.Addr() 和目标地址做字符串比较。

ParsePrefix 解析的到底是什么

netip.ParsePrefix 接收 CIDR 形式的字符串，返回一个 netip.Prefix 和错误值。这里的 Prefix 是“一个地址加前缀长度”，不是一段可以直接遍历的地址列表。

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    prefix, err := netip.ParsePrefix("10.24.8.7/24")
    if err != nil {
        panic(err)
    }
    fmt.Println(prefix)
    fmt.Println(prefix.Bits())
    fmt.Println(prefix.Addr())
}

这个例子的 Bits() 是 24，说明网络部分占 24 位；但输入地址是 10.24.8.7，它并不是这个 /24 的网络起点。若把 Addr() 的字符串当作网段名保存，后续配置比较就可能出现两个写法代表同一网段却无法相等的问题。

为什么 Masked 适合做配置规范化

Masked() 按前缀长度清掉主机位，返回规范的网络前缀。它解决的是“这个输入应该怎样稳定地展示和比较”，并不替代归属判断。

raw, _ := netip.ParsePrefix("10.24.8.7/24")
normalized := raw.Masked()

fmt.Println(raw)        // 10.24.8.7/24
fmt.Println(normalized) // 10.24.8.0/24

因此，接收用户填写的白名单、租户网段或配置文件时，可以先解析，再保存 Masked() 的结果。Bits() 则适合用在日志或校验提示里，让读者看到 /24、/64 这样的边界。

Contains 才是地址归属判断

假设配置里有 10.24.8.0/24，目标地址是 10.24.8.19。用 Prefix.Contains 直接判断即可：

prefix := netip.MustParsePrefix("10.24.8.0/24")
ip := netip.MustParseAddr("10.24.8.19")

if prefix.Contains(ip) {
    fmt.Println("allow")
} else {
    fmt.Println("deny")
}

这里 Contains 依据的是地址位与前缀长度，不是字符串前缀匹配。比如 10.24.80.1 的字符串看起来也以 10.24.8 开头，但它不一定属于同一个 /24；交给 Contains 才不会被这种巧合带偏。

IPv4、IPv6 和错误输入要分开处理

netip 的地址是值类型，IPv4 和 IPv6 都能放进 Addr，但地址族不是同一个概念。IPv4 前缀不应拿去判断 IPv6 地址；Contains 会给出 false。

func inPrefix(cidr, candidate string) (bool, error) {
    prefix, err := netip.ParsePrefix(cidr)
    if err != nil {
        return false, err
    }
    ip, err := netip.ParseAddr(candidate)
    if err != nil {
        return false, err
    }
    return prefix.Contains(ip), nil
}

外部配置、HTTP 参数和数据库字段都应该走带错误返回的 ParsePrefix 与 ParseAddr。MustParsePrefix 只适合源码中已经由测试覆盖的固定常量；把它用在用户输入上，会让一个格式错误升级成不可恢复的崩溃。

把三个动作放进一个可复用检查函数

实际项目通常既要判断，又要把规范化结果写入审计日志，可以把解析、规范化和归属判断放在同一处：

func checkNetwork(cidr, candidate string) (string, bool, error) {
    prefix, err := netip.ParsePrefix(cidr)
    if err != nil {
        return "", false, err
    }
    ip, err := netip.ParseAddr(candidate)
    if err != nil {
        return "", false, err
    }
    normalized := prefix.Masked()
    return normalized.String(), normalized.Contains(ip), nil
}

返回值中的第一个字符串是可存档的规范网段，第二个布尔值是归属结果，第三个值保留输入错误。这个顺序也方便调用方区分“格式不合法”和“地址合法但不在网段内”。

常见问题

ParsePrefix 会自动把 10.24.8.7/24 改成 10.24.8.0/24 吗？

不会。解析和规范化是两个动作；需要网络边界时显式调用 Masked()。

Prefix.Bits() 能判断地址是否在网段里吗？

不能。Bits() 只提供前缀长度，归属判断应使用 Contains。

为什么不直接比较 Prefix.Addr() 和目标地址？

Prefix.Addr() 表示前缀携带的地址，未必是规范网络地址；而且地址归属不是字符串相等关系，应该交给 Contains。

小结

ParsePrefix 负责把 CIDR 变成可操作的 Prefix，Bits 说明边界宽度，Masked 负责稳定表示，Contains 负责回答“地址是否属于这个网段”。把这四个语义分开，白名单、租户隔离和配置审计里的判断就不容易被字符串巧合或未规范化输入干扰。