当前位置：首页 > 文章列表 > Golang > Go教程 > Go netip.Prefix.Contains 的地址族判断：IPv4 映射地址与路由白名单

Go netip.Prefix.Contains 的地址族判断：IPv4 映射地址与路由白名单

来源：17golang原创 2026-08-28 02:41:13 0浏览收藏

路由白名单收到一个 IPv4-mapped IPv6 地址时，最容易出现的误判不是 CIDR 写错，而是调用方把地址族当成字符串格式处理。Go 的 netip 已经提供了值类型和前缀判断，关键在于先解析，再决定是否用 Addr.Unmap 统一 IPv4 语义。

把输入地址解析成 netip.Addr，对 IPv4-mapped IPv6 先调用 Unmap，再交给 Prefix.Contains；同时保留地址族检查，才能避免“文本看似不同、路由语义其实相同”的白名单漏洞。

要点速览

Prefix.Contains 会同时考虑前缀和地址族，不能只比较字符串前缀。
Addr.Is4In6 可识别 IPv4-mapped IPv6，Addr.Unmap 可把它还原为 IPv4。
白名单函数应区分解析失败、地址族不匹配和前缀未命中三种结果。
测试至少覆盖 IPv4、IPv4-mapped IPv6、同族未命中和非法输入。

为什么字符串比较会漏掉地址族边界

假设服务允许 192.0.2.0/24 访问管理接口。直接用字符串切分或正则判断开头，既无法表达掩码，也无法可靠处理 ::ffff:192.0.2.10。更麻烦的是，字符串形式的 IPv6 还可能存在压缩写法，文本不同不代表地址不同。

netip 的 Addr 是可比较的小值类型，Prefix 表示地址和位数。把“解析”和“是否在网段内”拆成两个阶段，白名单逻辑才有明确的失败位置。

先解析地址，再决定是否统一 IPv4 语义

下面的函数只做一件事：判断输入地址是否落在 IPv4 白名单中。ParsePrefix 负责得到规则，ParseAddr 负责得到请求地址，发现 Is4In6 后再用 Unmap 处理映射地址。

package main

import (
    "fmt"
    "net/netip"
)

func allowed(raw string, rule string) (bool, error) {
    prefix, err := netip.ParsePrefix(rule)
    if err != nil {
        return false, fmt.Errorf("invalid rule: %w", err)
    }

    addr, err := netip.ParseAddr(raw)
    if err != nil {
        return false, fmt.Errorf("invalid address: %w", err)
    }

    if addr.Is4In6() {
        addr = addr.Unmap()
    }
    if addr.BitLen() != prefix.Addr().BitLen() {
        return false, nil
    }
    return prefix.Contains(addr), nil
}

这里的顺序不要倒过来。先调用 Prefix.Contains 也许能得到一个布尔值，但把地址族不匹配和“确实不在网段内”混成同一个结果，会让审计日志很难解释。BitLen 检查则把规则和地址的 IPv4/IPv6 差异显式留下。

ParseAddr 识别 IPv4 mapped IPv6 后由 Unmap 统一，再由 Prefix.Contains 判断路由白名单

用一个最小实验核对四种输入

把下面的调用放进 main，可以直接看到四种边界：普通 IPv4 命中、IPv4-mapped IPv6 命中、同族未命中，以及非法地址。

func main() {
    rule := "192.0.2.0/24"
    cases := []string{
        "192.0.2.10",
        "::ffff:192.0.2.10",
        "192.0.3.10",
        "192.0.2.999",
    }
    for _, raw := range cases {
        ok, err := allowed(raw, rule)
        fmt.Printf("raw=%q allowed=%v err=%v\n", raw, ok, err)
    }
}

预期关注的是结果类型，而不是只看命中数量：前两项应为 allowed=true 且无错误，第三项为 allowed=false 且无错误，第四项应保留解析错误。这样，调用方可以把坏输入记为请求格式问题，而不是误报成策略拒绝。