Go net/netip Prefix.Masked 如何规范化网段键

做网段缓存、访问控制或路由索引时，输入经常不是网络地址本身，而是带有主机位的 CIDR，例如 192.168.10.37/24。如果直接把它的字符串当键，同一个网段可能因为主机位不同出现多条记录。Prefix.Masked() 的作用就是把主机位清零，返回规范化的 Prefix；保存前再检查 IsValid()，最后用 String() 生成稳定的网段键。

先把带主机位的 Prefix 变成规范输入

net/netip 的 Prefix 由地址和前缀长度组成。关键区别在于：ParsePrefix 负责解析 CIDR 文本，但不会替你清除被前缀长度之外的地址位；PrefixFrom 也只是按给定地址和位数构造值。要得到网络键，应该把解析和规范化拆成两个明确动作。

下面的函数把用户输入转换为键。这里使用可返回错误的解析函数，避免把外部配置中的拼写错误变成不可追踪的零值。

package netkey

import "net/netip"

func NetworkKey(text string) (string, error) {
	// 解析阶段只负责确认 CIDR 文本格式，不假设主机位已经清零。
	prefix, err := netip.ParsePrefix(text)
	if err != nil {
		return "", err
	}

	// Masked 按 Prefix.Bits 保留网络位，得到规范化前缀。
	normalized := prefix.Masked()
	if !normalized.IsValid() {
		return "", errInvalidPrefix
	}
	return normalized.String(), nil
}

例如，192.168.10.37/24 规范化后是 192.168.10.0/24，而 2001:db8:1:2::37/64 规范化后是 2001:db8:1:2::/64。这两个结果才适合拿来做缓存键、集合成员或路由表索引。

检查有效性，再生成稳定的网段键

不能只用 String() 的结果判断输入有效。零值 Prefix{} 的字符串表现为空，非法位数也不应进入业务存储；而 Masked() 对零值或其他无效前缀会返回零值。因此，键生成函数要把有效性判断放在规范化之后。

如果业务还要区分地址族，建议把地址族作为显式字段保留，或在键前加上固定前缀。不要把 IPv4 映射地址、IPv6 原生地址和业务层的字符串别名混在一起比较。

PrefixFrom、Addr.Prefix 和 Masked 怎么选

三者容易被混用，但用途不同：Addr.Prefix(bits) 会从地址生成指定长度的前缀并保留网络部分；PrefixFrom(ip, bits) 更像一个低开销的值构造器，调用者要自行决定是否随后 Masked()；已有 Prefix 时则直接调用 Masked() 最清楚。

func FromAddr(ip netip.Addr, bits int) (netip.Prefix, error) {
	// Addr.Prefix 会同时校验 bits 范围，并返回已按位处理的前缀。
	prefix, err := ip.Prefix(bits)
	if err != nil {
		return netip.Prefix{}, err
	}
	return prefix, nil
}

func FromRaw(ip netip.Addr, bits int) (netip.Prefix, error) {
	// PrefixFrom 不负责清除主机位；这里显式调用 Masked，避免键不稳定。
	prefix := netip.PrefixFrom(ip, bits).Masked()
	if !prefix.IsValid() {
		return netip.Prefix{}, errInvalidPrefix
	}
	return prefix, nil
}

代码中示例使用的 errInvalidPrefix 可以在包内定义为哨兵错误，例如 errors.New("invalid IP prefix")。生产代码应把解析错误和业务拒绝分开记录，这样排查配置问题时能知道是文本格式错，还是位数和地址族不匹配。

常见问题

调用 ParsePrefix 后为什么字符串还带主机位？

因为解析和掩码是两个动作。解析成功只代表文本符合 CIDR 形式，调用 Masked() 后才会得到规范网络地址。

Masked 会修改原来的 Prefix 吗？

不会。Prefix 是值类型，Masked() 返回新的规范化值；把返回值赋给变量即可。

可以直接比较两个 Prefix 是否属于同一网段吗？

先分别调用 Masked()，再比较规范值或比较 String()。如果还要判断包含关系，应使用 Contains，不要把字符串前缀匹配当成网络判断。