因x-forwarded-for易被伪造且代理链复杂，须用c.clientip()配合settrustedproxies校验真实ip；geoip数据库需全局预加载防阻塞；查库必须判err并处理未知地址与空字段，免费版对中国城市级坐标支持有限。
为什么不能直接用 net/http 解析 X-Forwarded-For 就查 GeoIP？
因为真实客户端 IP 往往被代理、CDN 或负载均衡器遮蔽，X-Forwarded-For 可能被伪造或拼接多个地址，直接取第一个不安全。Gin 的 c.ClientIP() 虽默认做了可信代理校验，但前提是正确配置 c.SetTrustedProxies()；否则返回的仍是代理 IP，查出来的地理位置就完全错位。
- 务必在初始化路由前调用
r.SetTrustedProxies([]string{"10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"})（按实际内网段调整） - 若部署在 Kubernetes 或云 LB 后，需把入口网关 IP 加入可信列表，否则
c.ClientIP()会退化为RemoteAddr - 不要依赖
c.Request.Header.Get("X-Real-IP")—— 这个头根本不是标准字段，Nginx 默认不透传，且无校验机制
MaxMind GeoLite2 本地数据库怎么加载才不卡住 Gin 启动？
GeoIP 数据库（如 GeoLite2-City.mmdb）文件通常 50–100MB，用 geoip2.Open() 直接加载会阻塞主线程，尤其在容器冷启动时可能超时失败。必须提前加载、复用 reader，而不是每次请求都打开文件。
- 在
main()函数里一次性调用geoip2.Open("/path/to/GeoLite2-City.mmdb")，赋值给全局变量（如var geoDB *geoip2.Reader） - 用
defer geoDB.Close()放在程序退出处，而非 handler 内 —— 每次 close/reopen 开销极大，且并发下易触发文件句柄耗尽 - 如果用的是 Go 1.21+，可配合
sync.Once做懒加载，避免测试时误加载未存在的路径
Gin middleware 中如何安全提取 IP 并查库，避免 panic？
geoip2.Reader.City() 和 .Country() 在 IP 不匹配任何网段时会返回 errors.Is(err, geoip2.ErrUnknownAddress)，不是 nil panic，但若忽略 err 直接访问 record.City.Names["en"] 会 panic。
- 必须检查 err：
if errors.Is(err, geoip2.ErrUnknownAddress) { /* 返回默认值或跳过 */ } - 语言名键不保证存在，优先用
record.City.Names["en"]， fallback 到record.City.Names["zh-CN"]或空字符串，别硬解record.City.Names["ja"] - 不要在 middleware 里做耗时格式化（如拼接完整地址字符串），只存原始结构体字段到
c.Set()，让业务 handler 按需取
func GeoIPMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
ip := c.ClientIP()
record, err := geoDB.City(net.ParseIP(ip))
if err != nil {
if !errors.Is(err, geoip2.ErrUnknownAddress) {
log.Printf("geoip lookup failed for %s: %v", ip, err)
}
c.Set("geo", nil)
c.Next()
return
}
c.Set("geo", map[string]interface{}{
"country": record.Country.Names["en"],
"city": record.City.Names["en"],
"lat": record.Location.Latitude,
"lon": record.Location.Longitude,
})
c.Next()
}
}
为什么查出来经纬度是 0.0, 0.0？
GeoLite2 免费版对部分国家（如中国、印度）城市级精度有限，很多 IP 段只定位到省级或更粗粒度，record.Location.Latitude 和 record.Location.Longitude 就会是 0。这不是代码 bug，而是数据库本身限制。
- 免费版
GeoLite2-City.mmdb不提供中国城市级坐标，仅含国家/地区信息；商用版才支持精确到区县 - 若业务强依赖经纬度，要么采购 MaxMind 商业许可，要么改用国内替代方案（如 GeoIP-Free 的 CN 精确库，但需自行维护更新）
- 不要对
Latitude == 0 && Longitude == 0做逻辑分支 —— 有些真实坐标就是赤道零点，应统一用math.IsNaN()判断无效值
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
