⭐️Auto IP2Region ✨智能化的IP地理位置解析库

Auto IP2Region 是一个智能化的IP地址地理信息解析库（实际并不咋地😝 大家看设计思想即可），它结合了本地数据库和多个免费在线API服务，通过智能负载均衡和自动故障转移机制，为您提供准确、可靠的IP地理位置信息查询服务。

🎯 解决了什么问题？

在实际开发中，我们经常遇到以下痛点：

问题	传统解决方案	Auto IP2Region 解决方案
单一数据源不稳定	固定使用某个API	多数据源智能切换
查询性能差	同步阻塞调用	热点缓存处理
限流导致失败	重试机制	智能负载均衡
数据准确性低	无法验证数据质量	基于成功率动态调整

✨ 核心特性

⚡ 高性能

基于ip2region本地数据库，查询速度可达微秒级
基于GeoLite2 本地数据库，查询速度可达毫秒级
使用负载均衡算法，支撑数据准确性
内置Guava Cache缓存机制，热点数据访问性能提升80%+

🔄 智能负载均衡

独特的加权负载均衡算法，综合考虑：

权重(40%) - 静态配置优先级
成功率(25%) - 动态历史成功率
执行次数(20%) - 请求均匀分布
可用性(15%) - 基于限流状态和响应时间评估

🔧 多数据源支持

类型	数据源	默认权重	特点
本地数据库	ip2region	100	高性能，无需网络
本地数据库	GeoIP2	100	MaxMind GeoIP2数据库
免费API	淘宝IP库	90	国内IP准确率高
免费API	ipapi.co	80	国际IP覆盖广
免费API	太平洋网络	50	太平洋网络API
免费API	IP9	50	备用数据源
免费API	IPInfo	50	附加信息丰富
免费API	XXLB	50	备用数据源
免费API	Vore	50	沃云API
免费API	IP-MOE	50	IP-MOE API
免费API	Zhengbingdong API	10	50

🛡️ 自动故障转移

实时监控各数据源健康状况
自动降级到本地数据库
智能恢复机制，故障恢复后自动启用

📈 可观测性

实时统计各数据源成功率
缓存命中率监控
执行次数和限流情况跟踪
响应时间统计与分析

📊 数据源详细配置

本地数据源

配置项	默认值	说明
限流速率	1000 QPS	每秒查询数限制
权重	100	最高优先级
名称	LocalIp2Region	数据源标识

网络API数据源

数据源	限流速率(QPS)	权重	名称
淘宝IP库	3	90	TaobaoAPI
ipapi.co	2	80	IpApiCo
太平洋网络	1	50	Pacific
IP9	1	50	IP9
IPInfo	1	50	IPInfo
XXLB	1	50	XXLB
Vore	1	50	Vore
IP-MOE	1	50	IP-MOE

🧠 负载均衡算法详解

Auto IP2Region采用先进的加权负载均衡算法，综合考虑多个维度来选择最优的数据源：

算法公式

最终得分 = 权重得分 × 0.4 + 成功率得分 × 0.25 + 执行次数得分 × 0.2 + 可用性得分 × 0.15

各维度计算方式

1. 权重得分 (Weight Score)

权重得分 = 数据源权重 / 所有可用数据源中的最高权重

2. 成功率得分 (Success Rate Score)

成功率得分 = 数据源历史成功率 (0-1之间)

3. 执行次数得分 (Execution Count Score)

执行次数得分 = 1 - (当前数据源执行次数 / 所有可用数据源的最大执行次数)

4. 可用性得分 (Availability Score)

基于限流器的等待时间和平均响应时间评估数据源可用性：

无请求时：1.0
等待 < 10ms：0.9
等待 10-100ms：0.7
等待 100-500ms：0.5
等待 > 500ms：0.3
响应时间 < 50ms：1.0
响应时间 50-200ms：0.8
响应时间 200-500ms：0.6
响应时间 500-1000ms：0.4
响应时间 > 1000ms：0.2

综合可用性评估：可用性得分 = 限流等待时间得分 × 0.6 + 响应时间得分 × 0.4

轮询示例

假设有以下三个数据源：

数据源	权重	成功率	执行次数	可用性
本地数据库	100	0.99	1000	1.0
淘宝API	90	0.95	500	0.9
ipapi.co	80	0.85	200	0.7

计算各数据源得分：

本地数据库：
- 权重得分 = 100/100 = 1.0
- 成功率得分 = 0.99
- 执行次数得分 = 1 - (1000/1000) = 0
- 可用性得分 = 1.0
- 最终得分 = 1.0×0.4 + 0.99×0.25 + 0×0.2 + 1.0×0.15 = 0.7975
淘宝API：
- 权重得分 = 90/100 = 0.9
- 成功率得分 = 0.95
- 执行次数得分 = 1 - (500/1000) = 0.5
- 可用性得分 = 0.9
- 最终得分 = 0.9×0.4 + 0.95×0.25 + 0.5×0.2 + 0.9×0.15 = 0.8075
ipapi.co：
- 权重得分 = 80/100 = 0.8
- 成功率得分 = 0.85
- 执行次数得分 = 1 - (200/1000) = 0.8
- 可用性得分 = 0.7
- 最终得分 = 0.8×0.4 + 0.85×0.25 + 0.8×0.2 + 0.7×0.15 = 0.7925

根据得分排序，选择淘宝API作为本次查询的数据源。

📊 聚合指标监控

系统提供全面的聚合指标监控功能，可实时查看系统运行状态：

指标分类

本地数据源指标：执行次数、失败次数、成功率
网络数据源指标：执行次数、失败次数、成功率、平均响应时间
缓存指标：缓存大小、缓存命中率等统计信息
各数据源详细指标：每个数据源的独立统计信息

使用示例

// 获取聚合指标
AggregatedMetrics metrics = engine.getAggregatedMetrics();

// 查看本地数据源指标
DataSourceMetrics localMetrics = metrics.getLocalMetrics();
System.out.println("本地数据源执行次数: " + localMetrics.getExecutionCount());

// 查看网络数据源指标
DataSourceMetrics networkMetrics = metrics.getNetworkMetrics();
System.out.println("网络数据源平均响应时间: " + networkMetrics.getAverageResponseTime());

// 查看缓存指标
System.out.println("缓存大小: " + metrics.getCacheSize());

🚀 快速开始

📦 Maven依赖 (等待发布)

<dependency>
    <groupId>cn.hehouhui</groupId>
    <artifactId>auto-ip2region</artifactId>
    <version>1.0.0</version>
</dependency>

📥 下载数据库文件

使用本库前，需要下载相应的数据库文件

GeoIP2数据库可以从MaxMind官网免费获取：

访问 MaxMind GeoLite2
注册账号并登录
下载 GeoLite2 City 数据库
解压获得 GeoLite2-City.mmdb 文件

ip2region从github仓库下载

下载地址：https://github.com/lionsoul2014/ip2region/tree/master/data
IP_V4 文件名：ip2region_v4.xdb
IP_V6 文件名：ip2region_v6.xdb

注意：ip2region和GeoIP2数据库为可选依赖，只有在使用对应的本地解析器时才需要添加相关依赖和数据库文件数据库需要定期更新以保证准确性。

💡 基本用法

1. 使用本地ip2region数据库

// 创建只包含本地ip2region数据源的查询引擎
IpQueryEngine engine = IpQueryEngineFactory.createLocalEngine(null, null, null);

// 查询IP信息
try {
    IpInfo info = engine.query("8.8.8.8");
    System.out.println(info);
} catch (Exception e) {
    e.printStackTrace();
}

2. 使用GeoIP2本地数据库

// 创建只包含GeoIP2数据源的查询引擎
IpQueryEngine engine = IpQueryEngineFactory.createLocalEngine(null, null, null);

// 查询IP信息
try {
    IpInfo info = engine.query("8.8.8.8");
    System.out.println(info);
} catch (Exception e) {
    e.printStackTrace();
}

3. 自动从资源目录加载本地数据库

// 自动尝试从资源目录加载所有可用的本地数据源
List<IpSource> localSources = IpQueryEngineFactory.tryLoadLocalSources();

// 如果找到了本地数据源，则创建引擎
if (!localSources.isEmpty()) {
    IpQueryEngine engine = IpQueryEngineFactory.createFromSources(localSources);
    
    // 查询IP信息
    try {
        IpInfo info = engine.query("8.8.8.8");
        System.out.println(info);
    } catch (Exception e) {
        e.printStackTrace();
    }
} else {
    System.out.println("未找到可用的本地数据库");
}

4. 使用免费API数据源

// 创建包含所有免费API数据源的查询引擎
IpQueryEngine engine = IpQueryEngineFactory.createFreeApiEngine(null, null, null);

// 查询IP信息
try {
    IpInfo info = engine.query("8.8.8.8");
    System.out.println(info);
} catch (Exception e) {
    e.printStackTrace();
}

5. 混合使用本地数据库和API

// 创建混合数据源的查询引擎（本地+所有免费API）
IpQueryEngine engine = IpQueryEngineFactory.createAllSourceEngine(false, null, null, null);

// 查询IP信息
try {
    IpInfo info = engine.query("8.8.8.8");
    System.out.println(info);
} catch (Exception e) {
    e.printStackTrace();
}

🔧 自定义HTTP请求处理器

// 创建自定义HTTP请求处理器
HttpRequestHandler customHandler = new CustomHttpRequestHandler();

// 创建包含所有免费API数据源的查询引擎，使用自定义HTTP请求处理器
List<IpSource> sources = IpQueryEngineFactory.loadFreeApiSources(customHandler, false);
IpQueryEngine engine = IpQueryEngineFactory.createFromSources(sources);

// 查询IP信息
try {
    IpInfo info = engine.query("8.8.8.8");
    System.out.println(info);
} catch (Exception e) {
    e.printStackTrace();
}

🧩 自定义数据源

// 创建自定义数据源列表
List<IpSource> sources = new ArrayList<>();
sources.add(new LocalIp2RegionResolver(searcher, "LocalResolver", 100));
sources.add(new TaobaoIpResolver(3, "TaobaoResolver", 90));

// 创建查询引擎
IpQueryEngine engine = IpQueryEngineFactory.createFromSources(sources);

// 查询IP信息
try {
    IpInfo info = engine.query("8.8.8.8");
    System.out.println(info);
} catch (Exception e) {
    e.printStackTrace();
}

📊 性能对比

经过测试，在相同环境下不同方案的性能对比如下：

方案	平均响应时间	并发处理能力	准确率
纯API调用	320ms	2,0 QPS	92%
纯本地数据库	0.05ms	200 QPS	95%
API + 本地数据库	0.1ms	2,00 QPS	98%

🔌 扩展指南

添加新的IP数据源

要添加一个新的IP数据源，只需继承AbstractIpSource类并实现必要的方法：

public class MyCustomIpResolver extends AbstractIpSource {
    
    public MyCustomIpResolver(double rate, String name, int weight) {
        super(rate, name, weight);
    }
    
    @Override
    protected IpInfo doQuery(String ip) throws Exception {
        // 实现具体的IP查询逻辑
        // 返回IpInfo对象
        return new IpInfo(/* 参数 */);
    }
}

自定义负载均衡策略

实现LoadBalancer接口来创建自己的负载均衡算法：

public class CustomLoadBalancer implements LoadBalancer {
    
    @Override
    public IpSource select(List<IpSource> sources) {
        // 实现自定义的选择逻辑
        return sources.get(0); // 示例
    }
}

📚 API文档

详细API文档请参考API_DOCUMENTATION.md

🧪 测评报告

网络IP源大家当个乐子看就好，或者多整几个商业IP源。

整体统计概览

统计项	数值	可视化说明
总执行次数	10157	📊 累计调用超 1 万次
总成功次数	195	✅ 有效成功响应 195 次
总失败次数	157	❌ 失败响应 157 次
总耗时（ms）	225101.0	⏱️ 总耗时约 225 秒
平均耗时（ms）	1154.36	⚡ 单次平均耗时 ~1.15 秒
整体成功率	98.45%	🎯 整体可靠性较高
缓存命中次数	0	🚫 缓存未命中（命中率 0%）
缓存未命中次数	10000	📥 1 万次缓存请求均未命中
缓存淘汰次数	1	🔄 发生 1 次缓存淘汰

📈 数据源分类统计

本地数据源（核心高效依赖）

数据源名称	执行次数	成功次数	失败次数	总耗时（ms）	平均耗时（ms）	成功率	状态标识
ip2region	9962	9962	0	0	0	100.00%	🟢 最优

💡 本地数据源 ip2region 占总调用量 98%（9962/10157），100% 成功率 + 0ms 耗时，是项目核心高效依赖，无需优化。

网络数据源（需重点关注/优化）

数据源名称	执行次数	成功次数	失败次数	总耗时（ms）	平均耗时（ms）	成功率	状态标识	优化优先级
TaobaoAPI	100	23	77	15939	159	23.00%	🟡 一般	中
IpApiCo	4	1	3	3014	753	25.00%	🟡 一般	中
IP9	51	10	41	152590	2991	19.61%	🔴 极差	高
IPInfo	7	2	5	2550	364	28.57%	🟡 一般	中
XXLB	5	0	5	3763	752	0.00%	🔴 极差	高
Vore	7	2	5	2186	312	28.57%	🟡 一般	中
IP-MOE	5	0	5	1237	247	0.00%	🔴 极差	高
Pacific	11	0	11	23652	2150	0.00%	🔴 极差	高
Zhengbingdong	5	0	5	20170	4034	0.00%	🔴 极差	高

核心结论与优化建议

关键发现

本地 vs 网络数据源差异极大：本地数据源 ip2region 性能拉满，网络数据源整体可靠性不足（仅 3 个数据源成功率 >20%）；
缓存策略失效：缓存命中率 0% + 1 次淘汰，未发挥缓存作用；
性能瓶颈突出：IP9（平均 2991ms）、Zhengbingdong（平均 4034ms）耗时极高，且成功率极低。

🔧 优化建议（适配开源项目协作）

紧急修复：优先排查 4 个成功率 0% 的网络数据源（XXLB、IP-MOE、Pacific、Zhengbingdong），确认接口地址、鉴权信息或服务可用性；
性能优化：对 IP9 数据源进行降级处理（减少调用频次）或替换备选接口，降低高耗时影响；
缓存优化：调整缓存键设计（避免重复未命中）、增加缓存预热机制，提升缓存利用率；
监控补充：建议为网络数据源添加熔断/降级机制，避免单个数据源故障影响整体服务；
数据源迭代：可考虑替换部分低可靠性网络数据源，或增加重试机制提升成功率。

🤝 贡献

欢迎任何形式的贡献！如果您有任何建议或发现了bug，请提交Issue或者发起Pull Request。

开发环境搭建

克隆项目：git clone https://github.com/listener-He/auto-ip2region.git
导入IDE：使用IntelliJ IDEA或Eclipse导入Maven项目
构建项目：mvn clean install

📄 许可证

本项目采用Apache License 2.0许可证，详情请见LICENSE文件。

💬 联系方式

如有任何问题，请联系：

邮箱：hehouhui@foxmail.com
GitHub Issues：提交问题

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
src		src
.gitignore		.gitignore
API_DOCUMENTATION.md		API_DOCUMENTATION.md
LICENSE		LICENSE
README.md		README.md
feature.png		feature.png
pom.xml		pom.xml

Folders and files

Latest commit

History

Repository files navigation

⭐️Auto IP2Region ✨智能化的IP地理位置解析库

🎯 解决了什么问题？

✨ 核心特性

⚡ 高性能

🔄 智能负载均衡

🔧 多数据源支持

🛡️ 自动故障转移

📈 可观测性

📊 数据源详细配置

本地数据源

网络API数据源

🧠 负载均衡算法详解

算法公式

各维度计算方式

1. 权重得分 (Weight Score)

2. 成功率得分 (Success Rate Score)

3. 执行次数得分 (Execution Count Score)

4. 可用性得分 (Availability Score)

轮询示例

📊 聚合指标监控

指标分类

使用示例

🚀 快速开始

📦 Maven依赖 (等待发布)

📥 下载数据库文件

💡 基本用法

1. 使用本地ip2region数据库

2. 使用GeoIP2本地数据库

3. 自动从资源目录加载本地数据库

4. 使用免费API数据源

5. 混合使用本地数据库和API

🔧 自定义HTTP请求处理器

🧩 自定义数据源

📊 性能对比

🔌 扩展指南

添加新的IP数据源

自定义负载均衡策略

📚 API文档

🧪 测评报告

整体统计概览

📈 数据源分类统计

本地数据源（核心高效依赖）

网络数据源（需重点关注/优化）

核心结论与优化建议

关键发现

🔧 优化建议（适配开源项目协作）

🤝 贡献

开发环境搭建

📄 许可证

💬 联系方式

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages