Go netip.Prefix Bits 怎样读取 CIDR 前缀长度

如果手里已经有一个 netip.Prefix，读取 CIDR 斜杠后的前缀长度不需要自己拆字符串，直接调用 p.Bits() 即可。IPv4 前缀的合法范围是 0 到 32，IPv6 是 0 到 128；Prefix 无效时，Bits() 返回 -1。

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

真正容易出错的地方有三个：把合法的 /0 当成无效值、把 IPv4 和 IPv6 的位数上限混用，以及以为 Bits() 会顺便把地址中的主机位清零。下面按这三个判断点拆开。

Bits 返回的到底是什么

Prefix 表示一个 IP 网络，内部由地址和前缀长度组成。对 192.0.2.0/24 调用 Bits()，结果就是 24；对 2001:db8::/32 调用，结果就是 32。它读取的是前缀长度，不是网络中可用地址数量，也不是地址的总位数。

package main

import (
	"fmt"
	"net/netip"
)

func describePrefix(text string) {
	// 先解析文本，避免把格式错误误当成 Bits 的数值问题。
	prefix, err := netip.ParsePrefix(text)
	if err != nil {
		fmt.Printf("%s: 解析失败: %v\n", text, err)
		return
	}

	// Bits 只读取斜杠后的前缀长度；地址族上限由 Addr 决定。
	family := "IPv6"
	if prefix.Addr().Is4() {
		family = "IPv4"
	}
	fmt.Printf("%s: %s, bits=%d, addr-bits=%d\n",
		text, family, prefix.Bits(), prefix.Addr().BitLen())
}

上面的示例中，192.0.2.0/24 的 bits 是 24、addr-bits 是 32；2001:db8::/32 的两个数分别是 32 和 128。这些是依据 API 语义推导的示例输出，文章制作过程没有把它们当成本地执行结果。

需要注意，/0 是合法前缀，表示不固定任何地址位。判断无效不能写成 prefix.Bits() == 0，而应检查 prefix.IsValid() 或判断 Bits() == -1。

用 ParsePrefix 处理文本输入

配置文件、环境变量和命令行参数通常先得到字符串。此时应把 ParsePrefix 的错误处理放在前面，再对成功返回的 Prefix 调用 Bits()。不要先用 strings.Split 拆斜杠，因为那样会把格式校验、地址族判断和位数范围重新分散到业务代码里。

package main

import (
	"fmt"
	"net/netip"
)

func prefixLength(text string) (int, error) {
	// ParsePrefix 同时处理地址、斜杠和前缀长度的格式。
	prefix, err := netip.ParsePrefix(text)
	if err != nil {
		return 0, fmt.Errorf("解析 CIDR %q: %w", text, err)
	}
	if !prefix.IsValid() {
		// 解析成功不等于业务对象有效，保留这层明确判断。
		return 0, fmt.Errorf("CIDR %q 产生了无效 Prefix", text)
	}
	return prefix.Bits(), nil
}

函数把“输入不是 CIDR”与“Prefix 处于无效状态”分成两条错误路径。对于可信的硬编码常量可以用 MustParsePrefix，但用户输入、配置输入和远端数据应优先用返回错误的 ParsePrefix。

官方文档还说明，IPv6 zone 不允许出现在 Prefix 中；如果输入带有类似 %eth0 的 zone，解析会失败。这个规则属于前缀文本格式，不应靠 Bits() 补救。

无效 Prefix 为什么返回 -1

Bits() 的返回类型是 int，合法前缀长度不会是负数，所以官方用 -1 表示无效。最常见的来源是直接调用 PrefixFrom 时传入负数，或传入超过地址族位数的 bits。

package main

import (
	"fmt"
	"net/netip"
)

func inspectConstructedPrefix() {
	ip := netip.MustParseAddr("192.0.2.10")
	// PrefixFrom 不会替调用方遮掉主机位，只接收地址和期望的 bits。
	good := netip.PrefixFrom(ip, 24)
	bad := netip.PrefixFrom(ip, 33)

	fmt.Println(good.Bits(), good.IsValid()) // 预期：24 true
	fmt.Println(bad.Bits(), bad.IsValid())   // 预期：-1 false
}

PrefixFrom(ip, 33) 对 IPv4 地址超出了 32 位上限，因此得到的 Prefix 无效，Bits() 是 -1。如果只输出 Bits 而不同时看 IsValid，调用方仍然需要明确约定负值意味着“拒绝该配置”。

这也解释了为什么 /0 不能作为无效标记：/0 在 IPv4 和 IPv6 都有明确含义，而 -1 才是这个 API 为无效 Prefix 保留的状态值。

Bits 不会自动清掉地址中的主机位

读取长度和规范化地址是两件事。ParsePrefix("192.0.2.10/24") 可以成功，但文档明确说明，解析后的地址位不会自动清零；需要规范 CIDR 网络地址时，再调用 Masked()。

package main

import (
	"fmt"
	"net/netip"
)

func showMaskedAddress() {
	// 解析保留输入地址，Masked 才负责把主机位清为网络地址。
	prefix := netip.MustParsePrefix("192.0.2.10/24")
	canonical := prefix.Masked()

	fmt.Println(prefix.Bits())      // 预期：24
	fmt.Println(prefix.Addr())      // 预期：192.0.2.10
	fmt.Println(canonical.String()) // 预期：192.0.2.0/24
}

因此，Bits() 可以回答“这个 Prefix 使用了多少位作为网络前缀”，Masked() 才回答“把它转换成规范的网络地址后是什么”。如果文章或配置系统只需要保存长度，直接保存 Bits；如果还要比较规范网段或输出标准 CIDR，再使用 Masked()。

把 Bits 放进配置校验

在实际配置入口，可以先解析，再用 IsValid 做对象级判断，最后根据业务需要读取 Bits。IPv4 与 IPv6 不应共用一个固定的上限判断；让 netip 根据地址族完成解析，再用 Bits 做业务范围限制会更清楚。

package main

import (
	"fmt"
	"net/netip"
)

func validateNetwork(text string) error {
	// 先让标准库确认这是有效 Prefix，再读取统一的前缀长度。
	prefix, err := netip.ParsePrefix(text)
	if err != nil {
		return err
	}
	if !prefix.IsValid() || prefix.Bits() 

这段校验把 API 合法性和业务策略分开：ParsePrefix 负责文本格式，IsValid 与 Bits 负责对象状态，最后的 8 才是示例业务规则。生产代码应根据路由范围、租户隔离或配置协议写出自己的阈值，不能把示例数字包装成通用网络安全结论。

常见混淆可以这样排除

如果只记一个调用关系，可以记成：ParsePrefix 负责把文本变成 Prefix，Bits 读取长度，IsValid 判断状态，Masked 负责规范地址。它们解决的是相邻但不同的任务。

相关问题

为什么 Bits 返回 0 仍然可能是有效值？ 因为 /0 表示零个固定网络位，是合法 CIDR 前缀。是否有效应看 IsValid，无效 Prefix 才会让 Bits 返回 -1。

PrefixFrom 会自动把地址改成网络地址吗？ 不会。它接收 IP 和 bits 构造 Prefix，不会像 Addr.Prefix 那样自动遮掉主机位；需要规范结果时调用 Masked()。

IPv4-mapped IPv6 地址的 Bits 上限按哪一族算？ 不能只看字符串外观。netip 将 IPv4-mapped IPv6 作为 IPv6 地址处理；把它交给 Prefix 相关 API 后，应以返回对象的地址族和 IsValid 结果为准。

归纳起来，netip.Prefix.Bits 是一个很小但很明确的读取接口：合法值是地址族范围内的前缀长度，无效值是 -1；它既不负责文本解析，也不负责网络地址规范化。把这三个职责分开，CIDR 配置校验就不容易混淆。