Gin框架黑白名单IP过滤中间件的拦截逻辑实现-Golang-PHP中文网

net.ParseIP 不能直接比对 CIDR 段，因其仅解析单个 IP 地址（net.IP），而 CIDR（如 "192.168.1.0/24"）表示网段范围，须用 net.ParseCIDR 解析为 *net.IPNet 后调用 Contains() 判断归属。

gin框架黑白名单ip过滤中间件的拦截逻辑实现

为什么 `net.ParseIP` 不能直接比对 CIDR 段？

很多人写黑白名单时，直接用 net.ParseIP 解析客户端 IP，再拿它跟配置的 "192.168.1.0/24" 字符串做字符串比较——这当然永远不匹配。CIDR 不是普通字符串，它代表一个网段范围，必须用 net.IPNet 来解析和判断包含关系。

正确做法是：先用 net.ParseCIDR 把配置项转成 *net.IPNet，再用它的 Contains 方法检查请求 IP 是否落在该网段内。

net.ParseIP("192.168.1.5") → 得到单个 IP 地址（net.IP）
net.ParseCIDR("192.168.1.0/24") → 得到网段对象（*net.IPNet），含掩码和网络地址
调用 ipNet.Contains(clientIP) 才能真正判断是否属于该子网

如何从 `c.ClientIP()` 获取真实客户端 IP？

Gin 的 c.ClientIP() 默认只看 X-Forwarded-For 和 X-Real-IP，但实际部署中常经过多层反向代理（Nginx → LB → Gin），如果没配置信任代理列表，它会返回最外层代理的 IP，导致黑白名单失效。

必须显式设置可信代理 CIDR 列表，并启用 SetTrustedProxies：

router := gin.Default()
// 必须在任何路由注册前调用
router.SetTrustedProxies([]string{"10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "127.0.0.1/32"})

不设或设空切片 → ClientIP() 只读请求头，不可信
设错（如漏掉 LB 的内网段）→ 返回代理 IP 而非用户真实 IP
若用云服务（如阿里云 SLB、AWS ALB），需查文档确认其源 IP 透传方式，有些需额外开启 X-Forwarded-For 插件

黑白名单逻辑冲突时谁优先？

常见错误是把白名单和黑名单写成两个独立循环，最后靠 return 顺序决定结果——这样容易漏掉“既在白名单又在黑名单”的边界情况，或者误判未命中任一列表的请求。

Gin框架 1.9.0

Gin框架 1.9.0版本源码包下载，版本号 1.9.0，适合需要 sonic JSON 支持、路由修复和内容协商改进的 Go Web 开发场景。

下载

推荐统一结构：先检查白名单（允许通行），再检查黑名单（明确拒绝），其余放行。逻辑必须严格分层：

if len(whitelist) > 0 {
    allowed := false
    for _, ipNet := range whitelist {
        if ipNet.Contains(clientIP) {
            allowed = true
            break
        }
    }
    if !allowed {
        c.AbortWithStatusJSON(http.StatusForbidden, gin.H{"error": "IP not in whitelist"})
        return
    }
}
// 白名单通过后，再查黑名单
for _, ipNet := range blacklist {
    if ipNet.Contains(clientIP) {
        c.AbortWithStatusJSON(http.StatusForbidden, gin.H{"error": "IP in blacklist"})
        return
    }
}

白名单存在时，不在白名单的请求直接拦截，不进黑名单逻辑
白名单为空，则跳过白名单检查，仅走黑名单
两个名单都为空 → 中间件不生效，所有请求放行（这是合理默认行为）

性能敏感场景下怎么避免重复解析 CIDR？

每次请求都调用 net.ParseCIDR 是浪费——配置项通常是静态的，应该在启动时一次性解析并缓存为 []*net.IPNet，中间件里只做 Contains 判断。

别在中间件函数体内解析字符串配置，而应在初始化阶段完成：

var (
    whitelistIPNets = parseCIDRs([]string{"10.0.0.0/8", "127.0.0.1/32"})
    blacklistIPNets = parseCIDRs([]string{"2.2.2.2/32", "3.3.0.0/16"})
)

func parseCIDRs(cidrs []string) []*net.IPNet {
    var nets []*net.IPNet
    for _, cidr := range cidrs {
        if ipNet, err := net.ParseCIDR(cidr); err == nil {
            nets = append(nets, ipNet)
        }
    }
    return nets
}