唯一正解是net.ParseCIDR解析CIDR得*net.IPNet，再调用Contains判断IP归属，它可靠支持IPv4/IPv6；禁用手算掩码、字符串匹配或位运算；须校验输入格式、检查ParseIP返回非nil、预解析缓存CIDR、明确定义黑白名单优先级。
net.ParseCIDR + net.IPNet.Contains 是唯一正解
别自己手算掩码、别用字符串前缀匹配、别写位运算逻辑——go 标准库早提供了可靠路径：net.parsecidr 解析 cidr 字符串得到 *net.ipnet，再调用其 contains 方法判断 ip 是否归属。这是唯一被标准库保证行为一致、且同时支持 ipv4 和 ipv6 的方式。
常见错误包括：
- 传给
net.ParseCIDR一个纯 IP（如"192.168.1.5"），它会返回nil并静默失败，因为格式必须是"IP/掩码位数"（如"192.168.1.0/24"） - 把
net.ParseIP("::ffff:192.168.1.1")得到的地址直接喂给Contains，却不先调用.To4()或归一化，导致 IPv4-mapped IPv6 地址被误判 - 用
ipnet.IP字段当“网络地址”去比对（比如"192.168.1.5/24"解析后ipnet.IP是192.168.1.5，不是192.168.1.0），这毫无意义
解析 CIDR 前必须校验输入格式
net.ParseCIDR 对非法输入不 panic，但返回 nil；你得主动检查。典型非法输入有：
- 缺掩码：如
"10.0.0.1"（应补为"10.0.0.1/32"或"10.0.0.0/24"） - IPv6 混端口未括号：如
"::1:8080"（正确是"[::1]:8080"，但 CIDR 本身不含端口，应只取"::1"部分） - 掩码写成点分十进制：如
"192.168.1.0/255.255.255.0"（Go 只认前缀长度，如/24）
实操建议：从配置或 HTTP 头读到 CIDR 字符串后，先用 strings.Contains(cidr, "/") 确保含斜杠，再用 net.ParseCIDR；若返回 nil，立刻拒绝该条规则，不要 fallback 到模糊匹配。
判断时必须先 ParseIP，再检查非 nil
net.ParseIP 对非法字符串（如 "256.1.1.1"、"192.168.1"、空格开头的字符串）返回 nil，这是合法行为，不是 bug。所有后续操作都必须以 ip != nil 为前提。
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
容易踩的坑：
- 直接对
net.ParseIP结果调用.To4()，而没判nil，导致 panic - 拿
X-Forwarded-For头第一个值（如"1.2.3.4, 10.0.0.1"）不做清洗就解析，遇到"127.0.0.1"或私有网段 IP 时仍参与判断，绕过真实拦截逻辑 - 忽略 IPv6 映射地址：客户端 IPv4 经代理可能传为
"::ffff:192.168.1.100"，需用ip.To4() != nil或ip.To16()统一处理
推荐做法：提取真实 IP 后，先 ip := net.ParseIP(clientIP)，再 if ip == nil { return false }，之后才进 Contains 流程。
黑白名单优先级必须显式定义
一个 IP 可能同时匹配多个 CIDR（例如 "192.168.1.5" 匹配 "192.168.1.0/24" 和 "192.168.0.0/16"），而 net.IPNet.Contains 本身不提供优先级。业务逻辑必须明确：
- 黑名单优先：只要命中任一黑名单项，立即拒绝
- 白名单优先：只放行至少命中一个白名单项的请求，其余全拒
- 顺序优先：按配置顺序遍历，首个匹配项生效（需注意配置加载顺序是否稳定）
缓存建议：预解析所有 CIDR 到 []*net.IPNet，避免每次请求重复调用 net.ParseCIDR；但切记，Contains 是轻量方法，无需额外缓存结果。
最易被忽略的一点：真实 IP 提取逻辑与黑白名单判断必须耦合在同一层——如果中间件里取的是 r.RemoteAddr，而配置里写的是公网 CIDR，那永远对不上。务必统一用 X-Forwarded-For 中可信跳数后的第一个公网 IP，并做私有地址过滤。
