Go netip.ParsePrefix 怎样解析 CIDR 字符串

我在处理配置里的网段字符串时，最容易踩到的坑不是“能不能解析”，而是“解析成功后地址是不是已经规范化”。Go 的 netip.ParsePrefix 会把类似 192.168.1.7/24 或 2001:db8::/32 的 CIDR 文本解析成 netip.Prefix，同时返回错误；但它不会自动把主机位清零。需要标准网络表示时，再调用 Masked。

实用做法是：外部输入使用 ParsePrefix 并检查 error；需要保存或比较规范网段时使用 prefix.Masked()；只有硬编码且确定合法的常量才考虑 MustParsePrefix。

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

先认识 ParsePrefix 返回的 Prefix

ParsePrefix 接收一个 CIDR 字符串，返回 (netip.Prefix, error)。IPv4 的前缀长度范围是 0 到 32，IPv6 是 0 到 128；返回的 Prefix.Addr() 是输入地址，Prefix.Bits() 是斜杠后的前缀长度。

这里的 Prefix 表示一个网络范围，而不是单独的主机地址。比如 10.20.30.0/24 的前 24 位确定网络，后 8 位可以匹配这个网段内的地址。

解析 IPv4 与 IPv6 CIDR

面对配置文件、环境变量或 HTTP 参数时，应把输入当作不可信文本，始终处理返回的错误。成功后可以读取地址族、前缀长度和字符串形式：

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    inputs := []string{"192.168.1.7/24", "2001:db8::/32", "10.0.0.1"}

    for _, raw := range inputs {
        // 外部字符串必须检查 error，避免把无效 CIDR 当成有效网段继续保存。
        prefix, err := netip.ParsePrefix(raw)
        if err != nil {
            fmt.Printf("解析失败 %q: %v\n", raw, err)
            continue
        }

        // Addr 保留解析到的地址，Bits 返回网络前缀长度。
        fmt.Printf("原始=%s 地址=%s 前缀长度=%d IPv6=%t\n",
            prefix, prefix.Addr(), prefix.Bits(), prefix.Addr().Is6())
    }
}

缺少斜杠、地址本身不合法、前缀长度超出地址族范围时都会得到错误。不要只根据字符串是否非空判断成功，也不要用字符串切分代替标准库解析。

用 Masked 得到规范网络地址

ParsePrefix("192.168.1.7/24") 可以成功，但输入地址的主机位仍可能保留在 Prefix.Addr() 中。若要把它作为网段键保存、比较或展示，调用 Masked 生成规范形式：

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    prefix, err := netip.ParsePrefix("192.168.1.7/24")
    if err != nil {
        // 解析失败时直接返回，避免对零值 Prefix 做后续业务判断。
        panic(err)
    }

    // ParsePrefix 不会清除主机位，Masked 才会得到 192.168.1.0/24。
    canonical := prefix.Masked()
    fmt.Println("输入形式:", prefix.String())
    fmt.Println("规范形式:", canonical.String())
}

这一区别很重要：如果缓存键有时保存 192.168.1.7/24，有时保存 192.168.1.0/24，同一个网络就可能出现两个键。规范化后再持久化或比较，可以把表示差异收敛到一个结果。

区分 ParsePrefix、MustParsePrefix 与 PrefixFrom

三个 API 的输入和失败策略不同：

如果地址来自 ParseAddr，也可以先解析地址再调用 PrefixFrom；但当原始输入本来就是 CIDR 文本时，直接使用 ParsePrefix 更能集中处理斜杠和前缀长度错误。

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    addr := netip.MustParseAddr("10.20.30.7")

    // PrefixFrom 适合已有 Addr 的场景，但它保留主机位，规范化要另调用 Masked。
    rawPrefix := netip.PrefixFrom(addr, 24)
    fmt.Println("PrefixFrom:", rawPrefix)
    fmt.Println("Masked:", rawPrefix.Masked())

    // MustParsePrefix 只用于代码内置的确定性常量，外部输入不要这样处理。
    fixed := netip.MustParsePrefix("2001:db8::/32")
    fmt.Println("固定前缀:", fixed)
}

处理 IPv6 zone、前缀长度和地址族

Prefix 是 CIDR 网络表示，IPv6 zone 不属于前缀文本的一部分。因此像 fe80::1%eth0/64 这样的输入会被拒绝。另一个常见错误是把 IPv4 的 32 位上限套到 IPv6，或把带 IPv4 映射形式的地址族当成普通 IPv4。

package main

import (
    "fmt"
    "net/netip"
)

func show(raw string) {
    // 将输入和错误一起输出，排查时能区分格式错误、zone 错误和长度越界。
    prefix, err := netip.ParsePrefix(raw)
    if err != nil {
        fmt.Printf("拒绝 %q: %v\n", raw, err)
        return
    }

    // Bits 是地址族相关的：IPv4 不超过 32，IPv6 不超过 128。
    fmt.Printf("接受 %q: %s，bits=%d\n", raw, prefix.Masked(), prefix.Bits())
}

func main() {
    show("2001:db8::/32")
    show("2001:db8::%eth0/64")
    show("192.0.2.1/33")
}

排错时先看斜杠是否存在，再看地址能否被 ParseAddr 接受，最后确认前缀长度是否落在该地址族允许的范围。错误信息应记录原始输入，但不要把未经处理的输入直接拼到 HTML、日志或命令中。

把解析结果接入包含判断

解析完成后，通常还要判断一个地址是否属于该网段。Prefix.Contains 会同时考虑地址族；IPv4 地址不会匹配 IPv6 前缀，零值地址也不会被当成有效成员：

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    network, err := netip.ParsePrefix("192.168.1.7/24")
    if err != nil {
        // 只有解析出有效 Prefix 后才进入包含判断。
        panic(err)
    }

    candidate := netip.MustParseAddr("192.168.1.42")
    // Contains 判断地址是否落在 Prefix 表示的范围内。
    fmt.Println(network.Masked().Contains(candidate))
}

如果业务要求比较“网络键”，先调用 Masked；如果只是判断地址归属，直接使用解析出的 Prefix 也能表达范围，但存储和展示时仍建议明确是否需要规范化。

常见问题

ParsePrefix 成功后为什么 String 不是网络地址？

因为它保留了输入地址中未被前缀覆盖的位。需要标准 CIDR 网络地址时调用 Masked().String()。

什么时候可以使用 MustParsePrefix？

只建议用于源码中写死、经过确认的常量或测试数据。配置和请求参数应使用 ParsePrefix 并显式处理 error。

PrefixFrom 会自动清除主机位吗？

不会。它根据已有地址和 bit 数构造 Prefix，主机位仍可能保留；要得到规范形式需要再调用 Masked。

IPv6 地址带 zone 能否直接写进 CIDR？

不能。Prefix 不接受 IPv6 zone；应先明确业务是否真的需要 zone，再把地址和网络前缀拆开处理。

总结一下：运行时 CIDR 文本用 netip.ParsePrefix，错误要显式处理；要统一网段表示就用 Masked；硬编码常量才考虑 MustParsePrefix；已经拥有 Addr 和前缀长度时再选择 PrefixFrom。