优先选github.com/oschwald/geoip2-golang，因其封装字段映射逻辑（如自动展开names["zh"]），而maxminddb-golang仅提供raw lookup需手动处理嵌套结构与空值，易导致中文名查不到或panic。
用 geoip2-golang 还是 maxminddb-golang？选错库直接查不到中文名
优先选 github.com/oschwald/geoip2-golang，别用 maxminddb-golang 原生库做业务查询。前者封装了字段映射逻辑（比如自动展开嵌套的 names["zh"]），后者只提供 raw lookup，你得自己写 struct tag 和 decode 逻辑——稍不注意就漏掉 country.names.zh 或 city.names.zh，返回空字符串还查不出原因。
常见错误现象：record.Country.Names["zh-CN"] 返回 nil，但 record.Country.Names["zh"] 才是正确键；Subdivisions 可能为空切片，直接取 [0] panic。
- 安装命令必须是：
go get github.com/oschwald/geoip2-golang（不是 fork 或旧版maxmind/geoip-api-golang） - 数据库必须是 GeoLite2-City.mmdb 或 GeoLite2-Country.mmdb，不能混用 CSV 或旧版 .dat
- 免费版下载地址固定为：
https://dev.maxmind.com/geoip/geolite2-free-geolocation-data?lang=en，需注册账号并接受许可协议
HTTP 请求里取 IP 必须做三层校验，否则线上查到全是“未知”
微服务通常跑在 Nginx / Traefik / ALB 后面，req.RemoteAddr 是上游代理地址，不是真实客户端 IP。硬解析它会导致所有请求都查出本地回环或内网段归属。
实操建议按顺序取值并校验：
- 先读
X-Real-IP头，若存在且通过net.ParseIP().IsGlobalUnicast()则直接用 - 否则取
X-Forwarded-For头，按逗号分割后从左到右遍历，对每个 IP 调用ip := net.ParseIP(trim(ipStr))→ip != nil && ip.IsGlobalUnicast() - 最后 fallback 到
req.RemoteAddr的 host 部分（strings.Split(req.RemoteAddr, ":")[0]），再做一次IsGlobalUnicast()
特别注意：::ffff:192.0.2.1 这类 IPv4-mapped IPv6 地址，必须先调用 ip.To4() 转成 IPv4 格式再查库，否则匹配失败返回空结构体。
在 Go 中使用 google/wire 实现编译时依赖注入——wire.NewSet、wire.Build、wire.Bind（接口→实现）、wire.Struct、wire.Value、wire.Interface
City 和 Country 查询性能差一倍，别在灰度开关里查 City
如果只是做国家级路由（如语言自动切换、区域限流、内容灰度），用 db.Country(ip) 就够了。它比 db.City(ip) 快 30%~50%，内存占用低一半，且对应 .mmdb 文件体积小——在容器内存受限场景下，这点差异直接影响 P99 延迟。
字段差异要点：
-
Country结构体只有IsoCode和Names字段，无Location、City、Subdivisions -
City结构体含Location.Latitude和Location.Longitude（不是Lat/Lng），字段名严格区分大小写 - 中文名统一用
Names["zh"]，"zh-CN"或"cn"都无效；没命中时应 fallback 到Names["en"]
热更新 mmdb 文件必须 reload reader，否则新数据永不生效
GeoLite2 数据库每月更新，但 geoip2.Open("GeoLite2-City.mmdb") 是静态加载——文件内容变更后，已打开的 *geoip2.Reader 实例仍读旧 mmap 区域，不会自动感知磁盘变化。
安全热更新方案：
- 启动时用
os.Stat()记录文件ModTime，定时轮询比对（例如每 5 分钟） - 发现变更后，新建
geoip2.Open()实例，原子替换全局变量（用sync.RWMutex保护） - 旧 reader 必须显式调用
.Close()，否则文件句柄泄漏，高并发下触发too many open files
容易被忽略的点：MaxMind 免费版数据库明确禁止 CDN 缓存或长期静态分发，每次部署必须校验 ModTime 是否最新，否则可能因数据过期导致地理位置误判。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
