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

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

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

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

假设服务允许 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 差异显式留下。

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

把下面的调用放进 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 且无错误，第四项应保留解析错误。这样，调用方可以把坏输入记为请求格式问题，而不是误报成策略拒绝。

接入 HTTP 中间件时保留失败原因

在 HTTP 服务里，allowed 返回的错误不应直接暴露给客户端。可以把错误写入结构化日志，并统一返回 400；合法但不在白名单的地址返回 403。两者分开后，运营人员才能知道是代理传来的地址格式异常，还是策略真的拒绝了请求。

如果地址来自可信代理头，还要先明确代理边界，不能无条件信任客户端提交的 X-Forwarded-For。netip 只负责准确解析和前缀判断，不替你完成代理可信链路的配置。

常见误区与回归检查

为什么不直接把所有地址都 Unmap

Unmap 的意义是处理 IPv4-mapped IPv6。对普通 IPv6 地址，统一动作没有业务价值，反而会掩盖规则本来应该支持 IPv6 的事实。先用 Is4In6 判断，语义更清楚。

前缀地址没有对齐怎么办

ParsePrefix 可以解析带主机位的前缀，但白名单配置最好在加载时校验并记录规范化结果。不要等每个请求到达时才反复解析配置。

测试只覆盖文本形式是否够用

不够。至少保留上面的四类输入，并额外加一条 IPv6 规则，确认 IPv4 地址不会因为字符串相似而误命中 IPv6 前缀。

相关问题

IPv4 地址能直接匹配 IPv6 前缀吗

不能把它当成字符串相似来判断。先确认规则和地址的地址族；如果业务只允许 IPv4，就只对 Is4In6 的映射地址做 Unmap，再进行匹配。

为什么命中结果和解析错误要分开

解析错误说明输入不是可用地址，未命中则说明地址合法但不在规则范围内。分开记录有助于定位代理头、客户端输入和白名单配置各自的问题。

Prefix.Contains 能替代完整的访问控制吗

不能。它只回答地址是否属于前缀，身份认证、可信代理配置、请求频率和审计仍需要由服务的其他层负责。

把地址族判断变成发布前清单

• 规则加载阶段调用 ParsePrefix，失败就拒绝启动或拒绝保存配置。
• 请求阶段调用 ParseAddr，把解析失败与策略拒绝分开记录。
• 只对 Is4In6 为真的地址调用 Unmap。
• 用 BitLen 和 Prefix.Contains 同时确认地址族与网段命中。

这样写，白名单判断的每一步都有可复查的语义：输入是什么、是否被统一、规则属于哪个地址族、最后为什么放行或拒绝。对于需要兼容双栈入口的 Go 服务，这比维护一组字符串前缀更稳。