Go net/netip 如何校验地址段：Prefix.Contains、掩码边界与配置解析

网关白名单经常不是一串固定 IP，而是配置里的几个 CIDR 网段。用字符串切分再自己做掩码，最容易把 IPv4、IPv6 和带主机位的前缀混在一起。Go 的 net/netip 可以把这件事收敛成“解析配置、解析来访地址、调用 Prefix.Contains”三步，同时把错误输入留在入口处。

真正适合放进访问校验函数的是已经通过 ParsePrefix 的 netip.Prefix；校验时直接调用 Contains，并额外明确地址族不匹配和 IPv6 zone 的处理结果。

把 CIDR 校验收口在 Prefix.Contains

白名单判断的输入有两个：配置中的网段，例如 192.0.2.0/24，以及请求方的地址，例如 192.0.2.18。netip.ParsePrefix 和 netip.ParseAddr 都返回显式错误，解析失败不会悄悄变成一个“空网段”。

package allowlist

import "net/netip"

func allowed(prefixText, addrText string) (bool, error) {
    prefix, err := netip.ParsePrefix(prefixText)
    if err != nil {
        return false, err
    }
    addr, err := netip.ParseAddr(addrText)
    if err != nil {
        return false, err
    }
    return prefix.Contains(addr), nil
}

这段代码的路径很短：ParsePrefix 先验证网段，ParseAddr 再验证地址，最后由 Prefix.Contains 给出布尔结果。把两次解析都放在入口处，调用方能区分“输入格式错误”和“地址格式正确但不在网段内”。

IPv4、IPv6 与 zone 不会被混为一谈

Prefix.Contains 不会把 IPv4 地址当作 IPv6 地址匹配，也不会把 IPv4-mapped IPv6 地址当成 IPv4。对于带 zone 的 IPv6 地址，prefix 会剥离 zone，Contains 会返回 false。这个边界很适合直接写成测试，而不是依赖调用方的猜测。

func TestAllowedFamilyBoundary(t *testing.T) {
    v4 := netip.MustParsePrefix("192.0.2.0/24")
    v6 := netip.MustParsePrefix("2001:db8::/32")

    if !v4.Contains(netip.MustParseAddr("192.0.2.18")) {
        t.Fatal("IPv4 address should match")
    }
    if v4.Contains(netip.MustParseAddr("2001:db8::18")) {
        t.Fatal("IPv6 address must not match IPv4 prefix")
    }
    if v6.Contains(netip.MustParseAddr("2001:db8::18%eth0")) {
        t.Fatal("zoned IPv6 address must not match")
    }
}

这里的 MustParsePrefix 只适合测试中的硬编码常量；线上配置仍应使用 ParsePrefix，把错误交给启动检查或配置热加载流程。

PrefixFrom 与 Masked：不要误读 host bits

如果前缀来自一个地址和位数，PrefixFrom 不会替你清除地址中的 host bits。例如用 192.0.2.18 和 24 组成前缀时，得到的地址仍带有 .18。需要规范化展示、比较或序列化时，再调用 Masked。

addr := netip.MustParseAddr("192.0.2.18")
raw := netip.PrefixFrom(addr, 24)
masked := raw.Masked()

fmt.Println(raw)    // 192.0.2.18/24
fmt.Println(masked) // 192.0.2.0/24

这不是 Contains 的替代方案，而是配置数据规范化的一步：原始前缀保留调用方给出的地址，Masked 才产生网络地址形式。若把两者混用，日志里看似相同的网段可能无法按字符串直接比较。

配置加载和请求校验各自做什么

实际服务里建议在加载阶段把字符串切片转换为 []netip.Prefix，请求到来后只解析客户端地址并遍历已验证的前缀。不要在每一次请求中重复解析同一份配置，也不要为了“容错”把解析错误当成空白名单。

func loadPrefixes(values []string) ([]netip.Prefix, error) {
    prefixes := make([]netip.Prefix, 0, len(values))
    for _, value := range values {
        prefix, err := netip.ParsePrefix(value)
        if err != nil {
            return nil, fmt.Errorf("invalid allowlist prefix %q: %w", value, err)
        }
        prefixes = append(prefixes, prefix)
    }
    return prefixes, nil
}

func matchAny(prefixes []netip.Prefix, addr netip.Addr) bool {
    for _, prefix := range prefixes {
        if prefix.Contains(addr) {
            return true
        }
    }
    return false
}

配置解析失败时服务应明确失败或拒绝加载；地址没有命中时返回普通的未授权结果。两种状态分开记录，排障时才能看出是发布配置错了，还是请求确实来自白名单之外。

常见问题：netip 地址段判断的几个边界

ParsePrefix 能接受带 IPv6 zone 的前缀吗？

不能。前缀使用 CIDR 表示，带 zone 的 IPv6 前缀会返回错误；需要先明确配置格式，而不是在业务匹配阶段猜测。

Prefix.Contains 会把 IPv4 和 IPv6 自动转换吗？

不会。不同地址族不匹配，IPv4-mapped IPv6 也不会按 IPv4 前缀处理。

什么时候需要调用 Masked？

当地址和位数来自动态输入，且你需要得到规范的网络地址、稳定日志或可比较的配置值时调用；单纯判断是否包含某个地址不必先做这一步。

把边界测试留在解析入口

这套做法的关键不是多写一个网络工具函数，而是让配置错误尽早暴露，让请求判断只处理已经成立的 netip.Prefix。用 ParsePrefix、ParseAddr 和 Prefix.Contains 分开表达三种责任，再用 IPv4/IPv6、zone 和 host bits 测试固定边界，后续替换配置来源或增加网段时都更容易复查。