首页 > Golang > Go问答

Go netip.Prefix.Contains 判断网段为什么出错：地址族、掩码长度与规范化

来源：17golang原创

时间：2026-08-27 22:39:03 501浏览收藏

把访问控制从 net.IP 换成 netip 后，最容易遇到的误判是：看起来同属一个网段，Prefix.Contains 却返回了 false。先别急着怀疑标准库，通常要先核对地址族、前缀是否有效，以及前缀地址有没有经过规范化。

Contains 只会在地址族一致、前缀有效且地址确实落入网络范围时返回 true；解析得到的主机位不会自动在所有场景下替你修正，输入边界要由调用方明确处理。

要点速览：

用 ParsePrefix 读取 CIDR，并检查解析错误。
用 IsValid 拦住无效前缀。
用 Masked 统一网络地址。
遇到 IPv4-mapped IPv6 和 IPv6 zone 时，不要把它们当作普通 IPv4。

先复现一个看似反常的网段判断

下面这段代码分别构造一个前缀和两个地址。第一个地址是普通 IPv4，第二个是 IPv4-mapped IPv6。它们打印出来都像是在表达同一台机器，但对 Prefix.Contains 来说，地址族并不相同。

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    prefix := netip.MustParsePrefix("192.168.10.0/24")
    v4 := netip.MustParseAddr("192.168.10.42")
    mapped := netip.MustParseAddr("::ffff:192.168.10.42")

    fmt.Println(prefix.Contains(v4))     // true
    fmt.Println(prefix.Contains(mapped)) // false
}

这不是字符串格式问题。官方文档明确区分 IPv4 与 IPv6：IPv4 地址不会匹配 IPv6 前缀，IPv4-mapped IPv6 也不会匹配 IPv4 前缀。调用方如果从代理头、日志或二进制协议拿地址，最好在进入判断函数前统一地址表达。

ParsePrefix 到 Contains 的地址族判断时间线，展示 IPv4 与 IPv4-mapped IPv6 的分叉

ParsePrefix 读到的前缀，为什么还要 Masked

ParsePrefix 能解析 CIDR，但它不会把被掩码遮住的主机位自动清零。例如 192.168.10.42/24 仍然保留了 42 这一段地址信息，属于 host bits present；这对展示原始输入有用，对比较规范的网络前缀则容易造成误解。

raw, err := netip.ParsePrefix("192.168.10.42/24")
if err != nil {
    panic(err)
}

canonical := raw.Masked()
fmt.Println(raw)       // 192.168.10.42/24
fmt.Println(canonical) // 192.168.10.0/24
fmt.Println(canonical.Contains(netip.MustParseAddr("192.168.10.42"))) // true

这里的重点不是把每个输入都改写，而是明确数据的角色：日志审计可以保留 raw，网段集合、缓存键和权限规则通常应该使用 canonical，最终由 Contains 给出 match 或不匹配结果。如果你直接用字符串作为规则键，未规范化的两个写法可能被误认为是两条规则。

PrefixFrom 也不会替你屏蔽主机位

代码动态生成前缀时常用 PrefixFrom。它接收一个地址和位数，但不会屏蔽地址中的主机位；需要稳定比较时，紧接着调用 Masked，并检查 Bits 是否在地址族允许范围内。

addr := netip.MustParseAddr("10.20.30.40")
raw := netip.PrefixFrom(addr, 24)
canonical := raw.Masked()

fmt.Println(raw)       // 10.20.30.40/24
fmt.Println(canonical) // 10.20.30.0/24

PrefixFrom、Masked 与 Contains 的规范化时间线，展示主机位清零后再判断

把判断函数写成可复查的边界检查

线上规则不要直接把 Contains 藏在一行条件里。先确认前缀有效，再决定是否把输入地址从 IPv4-mapped IPv6 转成普通 IPv4；如果地址带 IPv6 zone，也应按业务规则拒绝或单独处理。

func inNetwork(raw netip.Prefix, addr netip.Addr) bool {
    if !raw.IsValid() || !addr.IsValid() {
        return false
    }
    return raw.Masked().Contains(addr)
}

func main() {
    p := netip.MustParsePrefix("10.20.30.0/24")
    fmt.Println(inNetwork(p, netip.MustParseAddr("10.20.30.40")))
    fmt.Println(inNetwork(p, netip.MustParseAddr("10.20.31.40")))
}

这个包装函数没有偷偷做地址族转换，因此行为容易测试：无效前缀、零值地址、IPv4/IPv6 混用都返回不匹配。若业务确实允许映射地址，应在进入它之前显式调用 Unmap，并把这个决定写进测试用例。

测试别只覆盖一个 true

至少把“同族命中、同族不命中、跨族、映射地址、未规范化前缀、无效前缀”列成表驱动用例。尤其要保留跨族用例，它能防止后续有人为了让某个请求通过而加入隐式转换。

func TestInNetwork(t *testing.T) {
    p := netip.MustParsePrefix("10.20.30.42/24")
    cases := []struct {
        name string
        addr string
        want bool
    }{
        {"same family hit", "10.20.30.9", true},
        {"same family miss", "10.20.31.9", false},
        {"mapped ipv6", "::ffff:10.20.30.9", false},
    }
    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            got := inNetwork(p, netip.MustParseAddr(tc.addr))
            if got != tc.want {
                t.Fatalf("inNetwork(%s) = %v, want %v", tc.addr, got, tc.want)
            }
        })
    }
}