Go net.IPNet.Contains 怎样判断地址是否属于同一子网

在 Go 里判断一个 IP 是否属于某个子网，最稳妥的入口是先用 net.ParseCIDR 解析 CIDR，再调用返回的 *net.IPNet 的 Contains 方法。它回答的是“这个地址是否落在网络掩码覆盖的范围内”，不是“这台机器是否能连通该地址”。

官方文档：https://pkg.go.dev/net#IPNet.Contains

把“子网归属”交给 IPNet.Contains，把“输入是否合法”和“是否允许访问”留在调用方。IPv4 与 IPv6 要保持地址族和掩码长度一致，解析失败、空地址或非法掩码都不能被当成匹配成功。

Contains 判断的对象：网络而不是连通性

net.IPNet 由网络地址 IP 和网络掩码 Mask 组成。调用 Contains(ip) 时，标准库会把网络地址和待判断地址分别与掩码做按位与，再比较结果是否相同。两者相同，说明待判断地址落在该网络范围内。

这个判断适合做白名单、租户网段归属、监听地址分类等前置条件；它不会发包，也不会检查路由、端口、防火墙或对端服务状态。

用 ParseCIDR 构造可以直接判断的 IPNet

不要手动把字符串拆成 IP 和掩码。ParseCIDR 会同时返回解析出的地址和网络对象，网络对象中的 IP 已经是按掩码归一化后的网络地址。

package main

import (
    "fmt"
    "net"
)

func main() {
    // ParseCIDR 同时解析地址和前缀，并得到规范化的 IPNet。
    _, subnet, err := net.ParseCIDR("192.0.2.0/24")
    if err != nil {
        // 配置来源可能来自文件或请求，解析失败时不能继续做白名单判断。
        fmt.Println("无效的 CIDR:", err)
        return
    }

    candidates := []string{"192.0.2.18", "192.0.3.18"}
    for _, text := range candidates {
        // ParseIP 失败会返回 nil；Contains 对 nil 不会替调用方修复输入。
        ip := net.ParseIP(text)
        fmt.Printf("%s -> %t\\n", text, subnet.Contains(ip))
    }
}

对 192.0.2.0/24 来说，192.0.2.18 的前 24 位与网络地址一致，因此属于该子网；192.0.3.18 的网络部分不同，结果为 false。示例的重点是判断关系，不要把输出当成连通性探测结果。

IPv4 和 IPv6 为什么不能直接混着比

net.IP 底层是字节切片，Go 的网络包同时接受 4 字节 IPv4、16 字节 IPv6，以及 IPv4 映射到 IPv6 形式的地址。IPNet.Contains 会根据网络地址和掩码长度选择比较宽度：IPv4 网络使用 4 字节语义，IPv6 网络使用 16 字节语义；地址长度不匹配时不会强行当作同一地址族。

因此，使用 ParseCIDR 和 ParseIP 配对通常最省心。需要处理外部输入时，不要只看字符串里有没有冒号，而应让标准库解析，再根据目标网络的地址族决定是否接受。

package main

import (
    "fmt"
    "net"
)

func main() {
    // 目标网络明确是 IPv6，候选地址也应由 ParseIP 得到 IPv6 语义。
    _, v6net, err := net.ParseCIDR("2001:db8::/32")
    if err != nil {
        // 生产代码应把配置错误返回给上层，而不是默默放行。
        fmt.Println("无效的 IPv6 网段:", err)
        return
    }

    ip := net.ParseIP("2001:db8::10")
    fmt.Println(v6net.Contains(ip))
}

nil、非法 IP 和掩码边界要单独处理

net.ParseIP 解析失败时返回 nil。即使某个调用路径下 Contains(nil) 最终返回 false，也建议在边界层显式判断，这样日志能区分“合法地址不在网段内”和“输入根本不是地址”。

同理，手动构造 IPNet 时，如果 IP 与 Mask 长度不匹配，或掩码长度不是 4/16 字节，标准库内部无法得到有效的网络编号和掩码，结果应按不匹配处理。配置型系统最好在启动时用 ParseCIDR 预解析所有网段，避免请求处理阶段才暴露配置错误。

func inSubnet(cidr, address string) (bool, error) {
    // 先解析目标网段，把网段配置错误与地址判断错误分开。
    _, subnet, err := net.ParseCIDR(cidr)
    if err != nil {
        return false, fmt.Errorf("解析网段 %q: %w", cidr, err)
    }

    // 再解析候选地址，避免把 nil 当成一个普通地址继续传递。
    ip := net.ParseIP(address)
    if ip == nil {
        return false, fmt.Errorf("解析 IP %q: 无效地址", address)
    }
    return subnet.Contains(ip), nil
}

把 Contains 放在白名单判断的正确位置

实际项目里通常会预先解析一组网段，然后对每个请求地址逐个判断。Contains 只负责网段数学关系，业务层仍要决定“匹配后允许什么操作”、是否记录审计信息，以及多条网段重叠时采用哪条策略。

常见追问

Contains 能判断两个 IP 是否在同一子网吗？

可以把一个 IPNet 作为基准网络，再分别调用 Contains 判断两个地址；但它不会直接比较两个任意地址的共同最长前缀。

为什么 ParseCIDR 返回的第一个 IP 和 subnet.IP 可能不同？

第一个返回值是输入中的地址，第二个返回的 IPNet 表示按前缀归一化后的网络。判断子网归属时使用第二个返回值即可。

Contains 为 true 是否代表可以访问？

不是。它只说明地址落入掩码范围，端口、路由、防火墙、服务状态和业务授权仍需独立判断。