net/netip Prefix 判断客户端地址网段的实现方式

做客户端网段判断时，我更愿意把“解析”和“归属判断”拆成两个明确的接口：先用 netip.ParseAddr 得到地址，再用 netip.ParsePrefix 得到 CIDR 网段，最后交给 Prefix.Contains。这样非法输入可以单独返回错误，IPv4、IPv6 和特殊地址的边界也不会被一个字符串比较悄悄吞掉。

一、先把客户端地址和 CIDR 解析成可判断对象

HTTP 服务拿到的客户端地址通常还是字符串，例如 192.0.2.42；配置文件中的网段则是 192.0.2.0/24。不要直接用字符串前缀判断，因为 192.0.2.4 和 192.0.20.4 这种文本关系并不等于网络关系。netip 的价值在于把两者分别变成小型值类型，并让错误在入口处暴露。

package main

import (
	"fmt"
	"net/netip"
)

func inClientNetwork(rawIP, rawCIDR string) (bool, error) {
	// 先解析客户端地址，解析失败不能和“不在网段”混为一谈。
	ip, err := netip.ParseAddr(rawIP)
	if err != nil {
		return false, fmt.Errorf("解析客户端地址失败: %w", err)
	}

	// CIDR 单独解析，Prefix 负责描述一个 IPv4 或 IPv6 网段。
	prefix, err := netip.ParsePrefix(rawCIDR)
	if err != nil {
		return false, fmt.Errorf("解析客户端网段失败: %w", err)
	}
	if !ip.IsValid() || !prefix.IsValid() {
		return false, fmt.Errorf("地址或网段无效")
	}

	// Contains 只返回网段归属结果，不改变 ip 的地址族。
	return prefix.Contains(ip), nil
}

func main() {
	// 示例输入可来自请求头、连接地址或配置文件。
	ok, err := inClientNetwork("192.0.2.42", "192.0.2.0/24")
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(ok)
}

生产代码里，解析错误适合记录为输入问题或配置问题；false, nil 才表示地址格式正确，但不属于这个网段。这个区分对访问控制、租户路由和灰度名单都很重要。

二、用 Prefix.Contains 判断同地址族的客户端归属

Contains 的参数是 netip.Addr，接收者是 netip.Prefix。IPv4 前缀配 IPv4 地址、IPv6 前缀配 IPv6 地址时，判断语义最直接。网段的前缀长度决定比较多少个高位，例如 /24 只把前 24 位当作网络部分。

如果客户端地址来自代理头，还要先完成可信代理链的处理，再把最终选定的文本交给这个函数。Prefix.Contains 只解决“这个已解析地址是否属于这个已解析网段”，不替你决定哪个请求头可信。

三、把 PrefixFrom、Masked 与 Contains 的职责分开

已经有一个 Addr 和前缀位数时，可以用 PrefixFrom(addr, bits) 构造 Prefix。但官方文档特别说明，它不会把地址的主机位自动清零；如果需要规范化后的网段，应继续调用 Masked。因此，读取 CIDR 配置时优先使用 ParsePrefix，只有在程序已经把“地址 + 位数”拆开的场景才考虑 PrefixFrom。

addr := netip.MustParseAddr("198.51.100.73")

// PrefixFrom 保留传入地址的主机位；Masked 才得到规范网段。
rawPrefix := netip.PrefixFrom(addr, 24)
canonicalPrefix := rawPrefix.Masked()

// 用规范网段判断另一个地址，避免把主机位带进配置键或缓存键。
candidate := netip.MustParseAddr("198.51.100.9")
fmt.Println(canonicalPrefix.Contains(candidate))

MustParseAddr 只适合硬编码且确定合法的测试数据；请求参数、环境变量和配置文件仍应使用返回 error 的解析函数。

四、补上地址族、无效地址与 IPv6 zone 边界

有三个边界最容易在双栈服务里被忽略。第一，IPv4 地址不会匹配 IPv6 前缀，反过来也一样。第二，IPv4-mapped IPv6 地址不会被自动当成普通 IPv4 地址处理。第三，带 zone 的 IPv6 地址不会匹配前缀，因为 Prefix 不携带 zone。零值地址也不会匹配任何前缀。

因此，网段表最好按地址族分组，解析后先检查 Addr.Is4() 或 Addr.Is6()，再选择候选前缀。若业务确实允许把映射地址归一化为 IPv4，要在进入 Contains 前显式制定转换策略，而不是期待 API 替你转换。

相关问题

Prefix.Contains 会自动把 IPv4-mapped IPv6 转成 IPv4 吗？

不会。映射地址仍按 IPv6 处理，不能匹配 IPv4 前缀；需要业务层先决定是否做显式归一化。

PrefixFrom 和 ParsePrefix 应该怎么选？

外部 CIDR 文本用 ParsePrefix；已有 Addr 与位数时才用 PrefixFrom，并根据存储或比较需求调用 Masked。

解析失败能不能直接当作不在网段？

不建议。解析失败说明输入或配置有问题，应保留 error；只有成功解析后 Contains 返回 false，才是正常的不匹配。