最直接方式是用 net/http 中间件在请求入口拦截:优先解析可信代理头中的 X-Forwarded-For 首IP, fallback 到 RemoteAddr 去端口,经 net.ParseIP 校验后查 map[string]struct{} 黑名单;支持 CIDR 时统一转为 *net.IPNet 并用 Contains 判断,IPv4/IPv6 分片优化遍历。

用 net/http 中间件拦截黑名单 IP 最直接
Go 原生没有内置 IP 黑名单机制,但用中间件在请求入口处做判断最轻量、最可控。核心就是读取请求的客户端 IP,查表(或查集合),命中就返回 403。
注意:req.RemoteAddr 不能直接用——它带端口(如 192.168.1.100:54321),且可能被代理污染;应优先从 X-Forwarded-For 或 X-Real-IP 头提取,但必须结合可信代理列表校验,否则可伪造。
实操建议:
- 用
strings.Split(req.Header.Get("X-Forwarded-For"), ",")[0]取第一个 IP,并仅当请求来自已知可信反向代理(如 Nginx、Cloudflare)时才信任该头 - 最终 fallback 到
strings.Split(req.RemoteAddr, ":")[0],但只在无可信代理头时用 - 用
net.ParseIP(ipStr)校验格式,避免空字符串或非法输入导致 panic - 拦截逻辑放在
http.Handler包裹层里,不要侵入业务 handler
用 map[string]struct{} 存 IP 比切片快得多
黑名单规模一旦超过几百条,用 []string 线性遍历会明显拖慢请求处理——尤其是高频访问场景。用 map[string]struct{} 是 Go 社区共识:零内存开销、O(1) 查找、语义清晰(只存 key,不关心 value)。
常见错误现象:用 map[string]bool 或 map[string]int,纯属浪费内存;或忘记加锁,在并发写入时 panic。
实操建议:
- 定义类型别名提升可读性:
type IPBlacklist map[string]struct{} - 读操作无需锁,但增删(动态更新)必须用
sync.RWMutex保护 - 初始化后用
make(IPBlacklist),而不是nilmap,否则写入 panic - 检查存在性统一用
_, ok := bl[ip]; if ok { ... }形式
动态更新靠文件监听 + 原子替换,别 reload 进程
黑名单规则变更是常态,但每次改完都重启服务不可行。正确做法是监听文件变化(如 blacklist.txt),解析新内容,构建新 map,再原子替换旧 map —— 避免写时阻塞读,也避免中间态不一致。
性能影响:用 fsnotify 监听比轮询高效;替换 map 引用是无锁的(因为是指针赋值),但要注意旧 map 被 GC 前,正在执行的请求仍能安全读取它。
实操建议:
- 用
github.com/fsnotify/fsnotify监听文件WRITE和CHMOD事件(某些编辑器先 chmod 再写) - 解析时跳过空行和
#开头的注释行,每行一个 CIDR 或单 IP(如192.168.1.0/24或203.0.113.42) - 支持 CIDR 需用
net.ParseCIDR+ipNet.Contains(clientIP),但会略慢于纯 IP 匹配;若只需精确 IP,就别引入 CIDR 解析逻辑 - 替换时用
atomic.StorePointer或互斥写锁,确保所有 goroutine 看到的是同一份最新数据
生产环境必须考虑 CIDR 匹配与 IPv6 兼容性
单纯匹配字符串或 net.IP 等值,无法覆盖网段封禁需求(比如封整个云厂商出口段)。而 IPv6 地址长度和格式不同,net.ParseIP 虽支持,但比较和存储逻辑必须统一处理。
容易踩的坑:把 IPv6 地址转成字符串后做前缀匹配(如截取前 7 字符),结果错判;或用 strings.HasPrefix 判断 CIDR,完全忽略掩码位数。
实操建议:
- 黑名单内部统一用
*net.IPNet存 CIDR,单 IP 也转成/32(IPv4)或/128(IPv6)的*net.IPNet - 查询时遍历
[]*net.IPNet并调用ipNet.Contains(clientIP),这是标准且兼容 IPv4/v6 的方式 - 若黑名单条目多(>1k),可按地址族(IPv4/IPv6)分两个 slice,减少一半无效遍历
- 日志中记录被拦截的原始 IP 字符串(含 IPv6 方括号格式),方便排查
实际最难的不是写代码,是确认你拿到的 IP 真实且未被中间设备篡改——哪怕逻辑全对,源头错了,整个黑名单就形同虚设。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!











