Go netip.Prefix 如何判断网段包含：地址规范化、位长与边界测试

做 IP 白名单时，最容易藏着一个“看起来能跑”的错误：把请求地址转成字符串，再拿它和网段前缀做比较。Go 的 net/netip 已经把这件事收敛成 netip.Prefix.Contains，但它只在地址族、前缀有效性和输入规范都对齐时才会给出你期待的结果。

先看一条真实的网段判断链路

假设服务只允许 10.24.0.0/16 里的管理地址访问。基线实现不需要自己做位运算，直接把配置和请求地址解析成值类型：

package main

import (
    "fmt"
    "net/netip"
)

func allowed(rawPrefix, rawAddr string) (bool, error) {
    prefix, err := netip.ParsePrefix(rawPrefix)
    if err != nil {
        return false, fmt.Errorf("invalid prefix: %w", err)
    }
    addr, err := netip.ParseAddr(rawAddr)
    if err != nil {
        return false, fmt.Errorf("invalid address: %w", err)
    }
    return prefix.Contains(addr), nil
}

func main() {
    ok, err := allowed("10.24.0.0/16", "10.24.18.7")
    fmt.Println(ok, err) // true 
}

这一版的结果是可解释的：解析错误直接返回，合法地址再进入包含关系判断。不要把所有 false 都打成“配置错误”，因为地址合法但不在网段内，本来就是正常拒绝。

为什么 PrefixFrom 后还要关注 Masked

很多疑问来自这一行：

ip := netip.MustParseAddr("192.0.2.137")
prefix := ip.Prefix(24)
fmt.Println(prefix)        // 192.0.2.0/24
fmt.Println(prefix.Masked()) // 192.0.2.0/24

Addr.Prefix 会生成前缀；而当你使用 netip.PrefixFrom(ip, bits) 时，传入地址的主机位可能仍保留在值里。此时 Masked 返回规范形式，把 Bits() 之外的低位清掉。判断包含关系时，Contains 按网络前缀工作；做配置去重、日志对比或作为 map key 时，建议统一保存 prefix.Masked()。

这也是一次很实用的性能案例：先把启动时读到的 CIDR 规范化并缓存，热路径只解析请求地址和调用 Contains，不要每次请求都重新拆字符串、算掩码。

压测前先把三个边界补进测试

小型基准很容易测出“函数很快”，却没测出规则是否正确。下面三组用例分别验证包含、越界和地址族不匹配：

func TestPrefixContains(t *testing.T) {
    cases := []struct {
        name   string
        prefix string
        addr   string
        want   bool
    }{
        {"inside", "10.24.0.0/16", "10.24.255.255", true},
        {"outside", "10.24.0.0/16", "10.25.0.1", false},
        {"family-mismatch", "10.24.0.0/16", "2001:db8::1", false},
    }
    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            p := netip.MustParsePrefix(tc.prefix)
            ip := netip.MustParseAddr(tc.addr)
            if got := p.Contains(ip); got != tc.want {
                t.Fatalf("Contains(%s) = %v, want %v", tc.addr, got, tc.want)
            }
        })
    }
}

官方实现明确说明：IPv4 不匹配 IPv6 前缀，IPv4-mapped IPv6 也不会按普通 IPv4 前缀处理；零值地址不会匹配任何前缀，带 zone 的 IPv6 地址同样返回 false。这些不是“异常兼容”，而是 Contains 的契约，值得直接写进回归测试。

结果对比：字符串方案为什么不值得保留

• 字符串前缀比较：无法表达 /16 的位边界，容易把 10.24.1.9 和 10.240.1.9 的文本形状混为一谈。
• 手写整数掩码：要自己处理 IPv4、IPv6、字节序和非法输入，维护成本随着地址族增加。
• netip.Prefix.Contains：值类型、解析错误显式、地址族规则清晰，适合把判断放在配置加载后的热路径。

真正的边界是配置来源。如果 CIDR 来自环境变量或数据库，先在加载阶段拒绝非法前缀；如果请求地址来自代理头，先确认代理链可信，再把最终地址交给 ParseAddr，不要把“取哪个头”混成网段判断问题。

常见问题

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

不会。官方文档把 IPv4-mapped IPv6 单独列为不匹配普通 IPv4 前缀的情况，需要在边界层明确统一地址表示。

为什么合法地址调用 Contains 仍然是 false？

最常见原因是地址不在网段、地址族不同、前缀无效，或 IPv6 地址带了 zone。分别记录解析结果和包含结果，就能区分这些情况。

PrefixFrom 和 Masked 应该怎么选？

只做一次判断时重点是 Contains；要把前缀存配置、做去重或比较时，用 Masked 统一成网络地址形式。

把判断收口成一条可复用规则

解析阶段负责发现输入错误，规范化阶段负责稳定表示，Contains 负责回答“是否属于这个网段”。这三个职责分开后，白名单、路由表和租户网段校验都能复用同一套测试边界，后续升级 Go 版本也更容易对照标准库契约复核。