Go netip 怎么做 CIDR 白名单：解析、匹配与失败回归

给后台接口加 IP 白名单时，最先出现的通常不是复杂攻击，而是配置写成了字符串、IPv4 和 IPv6 混在一起，或者把 10.2.0.0/16 错当成了一个普通地址。Go 的 net/netip 提供了更适合这类规则的值类型：先把 CIDR 解析成 netip.Prefix，再用 Contains 判断请求地址是否落在网段内。

先把字符串配置变成可判断的规则

假设配置文件里有一组 CIDR：

allowlist:
  - 10.2.0.0/16
  - 2001:db8:10::/48

请求到达时，真正需要回答的是“这个地址是否属于某个已经验证过的网段”。如果每次请求都重新拆字符串，不仅浪费，还会把解析错误拖到线上路径。更稳的做法是启动时完成转换。

type Allowlist struct {
    prefixes []netip.Prefix
}

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

这里把错误返回给启动流程，调用方可以直接拒绝加载配置。不要偷偷跳过非法条目，否则管理者以为白名单生效，实际却少了一条规则。

用 Prefix.Contains 做 IPv4 和 IPv6 匹配

请求地址从连接层拿到后，先用 netip.ParseAddr 转换，再依次检查前缀：

func (a Allowlist) Contains(value string) (bool, error) {
    addr, err := netip.ParseAddr(value)
    if err != nil {
        return false, fmt.Errorf("invalid IP %q: %w", value, err)
    }
    for _, prefix := range a.prefixes {
        if prefix.Contains(addr) {
            return true, nil
        }
    }
    return false, nil
}

10.2.4.9 会命中 10.2.0.0/16，而 10.3.0.1 不会；IPv6 也按同样的接口判断。若前缀和地址的版本不同，Contains 不会把它们当作同一地址族，调用方不需要自己做字符串前缀判断。

把规则检查放到加载阶段

能运行的白名单还不够，配置本身也要有边界。管理接口通常不应该接受 0.0.0.0/0 这类全网段规则；重复前缀虽然不影响判断，却会让审查和排错变得困难。

func validatePrefix(prefix netip.Prefix) error {
    if !prefix.IsValid() {
        return errors.New("prefix is invalid")
    }
    bits := prefix.Bits()
    if bits == 0 {
        return fmt.Errorf("prefix %s is too broad", prefix)
    }
    return nil
}

实际项目可以根据业务放宽规则，例如内部代理服务允许全网段但必须经过额外鉴权。关键是把这个决定写成显式校验，而不是把安全边界藏在调用者的约定里。

如果配置来自环境变量，建议先按逗号拆分、去除首尾空白，再交给同一个构造函数；不要为环境变量再写一套 CIDR 解析逻辑。

白名单顺序和代理地址要先说清

多个前缀同时命中时，结果仍然是允许，但日志最好记录第一条命中的规则，便于知道请求通过了哪条配置。真正容易出错的是代理场景：应用看到的可能是反向代理地址，而不是客户端地址。

如果使用 X-Forwarded-For 或 X-Real-IP，必须先确认哪些代理是可信的，再决定取哪个地址。不能直接相信客户端自己提交的头字段，然后用白名单给它放行。白名单组件只负责匹配，可信代理链属于网络边界配置。

用边界样例把失败路径固定下来

测试不要只写一个命中例子。至少覆盖网段首地址、网段末地址、相邻地址、错误掩码、IPv4/IPv6 混用和空配置。

func TestAllowlistContains(t *testing.T) {
    list, err := NewAllowlist([]string{"10.2.0.0/16", "2001:db8:10::/48"})
    if err != nil {
        t.Fatal(err)
    }
    cases := []struct {
        ip string
        ok bool
    }{
        {"10.2.0.1", true},
        {"10.2.255.255", true},
        {"10.3.0.1", false},
        {"2001:db8:10::9", true},
        {"2001:db8:11::9", false},
    }
    for _, tc := range cases {
        got, err := list.Contains(tc.ip)
        if err != nil || got != tc.ok {
            t.Fatalf("ip=%s got=%v err=%v want=%v", tc.ip, got, err, tc.ok)
        }
    }
}

另外单独测试非法配置：

func TestNewAllowlistRejectsBadCIDR(t *testing.T) {
    _, err := NewAllowlist([]string{"10.2.0.0/99"})
    if err == nil {
        t.Fatal("expected CIDR validation error")
    }
}

上线前按四个动作验收

第一步，在启动配置里放一个非法 CIDR，确认服务直接拒绝启动并指出原始值；第二步，用网段边界地址请求，核对允许和拒绝结果；第三步，经过可信代理访问，确认日志记录的是约定的客户端地址；第四步，临时加入全网段规则，确认加载校验能阻止它进入生产。

这套验收把解析、匹配、网络边界和配置审查串在一起。只检查 Contains 返回值，无法证明生产请求拿到的是正确地址。

常见问题

netip.ParsePrefix 和 net.ParseCIDR 怎么选？

新代码只需要地址和前缀值时，netip 的类型更直接，也避免了指针形式的 net.IP。已有代码大量依赖 net.IPNet 时可以渐进迁移，不必一次改完整个网络层。

IPv4 地址能匹配 IPv6 前缀吗？

不能把两个地址族混着判断。配置和请求地址都先解析成 netip 后，Prefix.Contains 会按地址族执行匹配。

白名单为空时应该允许还是拒绝？

管理接口通常更适合默认拒绝，并在配置加载时明确记录“没有允许网段”。公共服务则可能不启用白名单；这应该是上层开关的决定，不要让空切片悄悄改变安全策略。

把网络边界写成可验证的组件

CIDR 白名单的核心代码并不长，难点在于把坏配置、地址族、可信代理和边界样例一起纳入工作流。启动时解析，访问时匹配，测试里保留首尾边界，日志记录实际命中规则，后续换存储或接入管理后台时也不容易丢掉这条安全链路。