Go net/netip怎样判断地址是否属于指定网段怎样完成一个可复用的最小示例

我在做访问来源分组时，最容易写错的不是 CIDR 本身，而是把字符串比较、地址解析和网段判断混在一起。Go 的 net/netip 已经把这条链路拆成了清晰的值类型：用 netip.Addr 表示地址，用 netip.Prefix 表示“地址加前缀长度”，最后调用 Prefix.Contains 判断是否包含。这样既能覆盖 IPv4，也能覆盖 IPv6，输入错误还能在入口处返回。

实际项目里可以把“地址字符串 + 网段字符串”交给一个小函数：先分别解析，再让网段调用 Contains。不要手动切割点号、比较字符串，也不要把解析失败的零值当成合法地址。

本文的示例只解决一个边界明确的问题：判断一个地址是否属于一个指定的 CIDR 网段，不扩展到路由表、ACL 优先级或并发缓存。

netip 的地址和网段分别表示什么

netip.Addr 是不可变、可比较的 IP 地址值；netip.Prefix 则在地址基础上增加前缀位数，例如 192.0.2.0/24。判断时，前缀对象已经携带了网络范围，调用 Contains 会返回一个布尔值。

这里有一个实用区分：Addr 是单个地址，Prefix 是一个范围。只拿两个 Addr 做相等比较，无法表达“属于网段”；只有把目标网段解析成 Prefix，才有了 Contains 的判断语义。

先解析输入，再调用 Contains

外部输入应该使用带错误返回的解析函数。下面的函数把解析、类型匹配和包含判断放在一个稳定入口里，调用方只需要处理一个 bool 和一个 error。

package main

import (
    "fmt"
    "net/netip"
)

// addrInPrefix 只负责判断地址是否属于给定 CIDR，并把输入错误交给调用方。
func addrInPrefix(addrText, prefixText string) (bool, error) {
    // 解析地址失败时不要继续使用 Addr 的零值。
    addr, err := netip.ParseAddr(addrText)
    if err != nil {
        return false, fmt.Errorf("解析地址 %q: %w", addrText, err)
    }

    // ParsePrefix 会同时解析网络地址和前缀位数，例如 192.0.2.0/24。
    prefix, err := netip.ParsePrefix(prefixText)
    if err != nil {
        return false, fmt.Errorf("解析网段 %q: %w", prefixText, err)
    }

    // Contains 负责完成真正的网段包含判断；IPv4/IPv6 类型不匹配时不会误判为包含。
    return prefix.Contains(addr), nil
}

func main() {
    cases := [][2]string{
        {"192.0.2.18", "192.0.2.0/24"},
        {"192.0.3.18", "192.0.2.0/24"},
        {"2001:db8::18", "2001:db8::/32"},
    }

    for _, item := range cases {
        ok, err := addrInPrefix(item[0], item[1])
        if err != nil {
            // 真实服务中可以把错误转换成 400 或结构化日志。
            fmt.Printf("%s in %s: error: %v\n", item[0], item[1], err)
            continue
        }
        fmt.Printf("%s in %s: %t\n", item[0], item[1], ok)
    }
}

函数的关键不在于代码量，而在于顺序：输入先变成类型安全的值，再由 Prefix.Contains 解释范围。这样网段字符串写错时会得到明确错误，而不是静默得到 false。

Contains 的边界：IPv4、IPv6 和规范化

Contains 适合判断同一地址族的关系。比如 IPv4 地址和 IPv4 网段可以正常匹配；IPv6 地址应与 IPv6 网段配对。不要把“看起来像 IPv4 的 IPv4-mapped IPv6 地址”自动当成普通 IPv4，若业务需要统一表示，应在入口处明确调用 Addr.Unmap 或制定统一的输入约定。

如果网段写成了主机位不为零的形式，例如 192.0.2.18/24，解析结果仍然可以表达一个前缀，但工程上最好在配置加载时调用 prefix.Masked() 得到明确的网络地址表示，或者直接拒绝非规范配置。选择哪一种取决于配置契约：允许用户输入“包含关系”还是要求输入标准 CIDR。

把判断函数放在哪里最合适

在 HTTP 白名单、租户网段配置或内网来源分类中，建议把解析动作放到配置加载阶段，把 Prefix 保留下来；请求到达时只解析来访地址并循环调用已准备好的 Contains。如果网段来自每次请求的参数，则仍要保留错误信息，避免把非法输入与合法但不属于网段混成同一种结果。

常见问题

为什么不用字符串前缀判断？

字符串前缀没有 CIDR 的位级语义，像 192.0.2.1 和 192.0.20.1 就可能被错误关联。应先解析成 Addr 和 Prefix。

ParseAddr 失败时可以继续调用 Contains 吗？

不建议。解析函数返回的错误代表输入没有形成有效地址；应该立即返回错误，让上层决定提示、拒绝或记录。

Contains 能代替网段重叠判断吗？

不能。判断两个网段是否有交集应使用 Prefix.Overlaps；Contains 的参数是一个 Addr，语义是“某个地址是否在这个前缀内”。

归纳起来，最小可靠写法就是“解析地址、解析前缀、调用 Contains、按契约处理规范化”。把这四步固定在边界函数中，后续无论接配置文件还是 HTTP 请求，都不必重复手写 IP 网段算法。