c.clientip()不能直接用于黑名单判断，因其默认仅信任本地回环，线上经nginx/cdn/slb等代理后返回的多为127.0.0.1或内网地址，而非用户真实出口ip，导致黑名单规则完全失效。
为什么 c.ClientIP() 不能直接用作黑名单判断依据
c.ClientIP() 在线上环境几乎必然返回 127.0.0.1 或内网地址（如 10.0.0.3），不是用户真实出口 IP。它默认只信任本地回环，而生产环境普遍经过 Nginx、CDN、SLB 等反向代理，请求头被层层转发后，c.ClientIP() 已失去意义。
直接用它查黑名单，等于永远放行所有流量——规则形同虚设。
- 确认你是否配置了
engine.SetTrustedProxies()：没配就别碰c.ClientIP() - 检查 Nginx 是否设置了
proxy_set_header X-Real-IP $remote_addr；没设就别读X-Real-IP - 若走多层代理（比如 Cloudflare → Nginx → Gin），必须用
X-Forwarded-For并取最左“非私有 IP”，且该请求来源 IP 必须落在你配置的可信网段里
如何安全提取真实客户端 IP
不能信任任意头字段，必须按可信链路降级解析，并校验代理来源合法性。
- 优先取
c.Request.Header.Get("X-Real-IP")：伪造成本高，前提是 Nginx 正确设置了该头 - fallback 到
c.Request.Header.Get("X-Forwarded-For")：用strings.Split(header, ",")[0]取最左值，再用net.ParseIP()解析；但仅当c.ClientIP()（此时是上一级代理 IP）在你配置的可信网段（如"192.168.0.0/16"）内才可信 - 最后 fallback 到
c.Request.RemoteAddr：必须先net.SplitHostPort()拆解，再net.ParseIP()提取纯 IP；仅限直连调试，不可用于线上 - 所有 IP 字符串必须经
net.ParseIP()转为net.IP再参与后续逻辑；未解析就传给net.IPNet.Contains()会静默失败
黑名单数据结构与匹配逻辑怎么选
万级以下条目，map[string]struct{} 是唯一合理选择：O(1) 查询、零 GC 压力、内存最小、热更新简单。
- 初始化：
blacklist := make(map[string]struct{}) - 加载单个 IP：
blacklist["192.168.1.100"] = struct{}{} - 判断是否命中：
_, blocked := blacklist[ip.String()] - 别用
[]string遍历查找——1000 条就要平均 500 次字符串比较，QPS 上千时毛刺明显 - 别用
sync.Map——除非你每秒增删上千次，否则它比普通map+sync.RWMutex更慢、更占内存 - 支持 CIDR 时必须用
net.IPNet.Contains()，不能用strings.HasPrefix()；后者在 IPv6 下完全不可靠，也无法处理掩码对齐
中间件里怎么写才不踩坑
核心原则：路径豁免、热更新支持、错误静默容忍。
- 豁免健康检查路径，如
/healthz、/metrics，避免监控探针被误拦 - 黑名单规则应通过
atomic.Value包裹map[string]struct{}实现无锁热更新，避免每次请求加锁或拷贝 - IP 解析失败（如空字符串、非法格式）应视为非黑名单 IP，不 panic、不 abort，继续走下游
- 不要在中间件里做耗时操作（如查 DB、Redis），黑名单必须预加载到内存；如需动态加载，用 goroutine 定期拉取并原子替换
- 日志中记录被拦截的 IP 和路径，但别打全量请求体——可能含敏感信息
真实 IP 提取和黑名单匹配这两个环节，任何一个出错都会让整套机制失效。最容易被忽略的是代理链校验和 CIDR 解析方式——它们不是“能跑就行”，而是安全边界的硬性要求。
