主题
starter-biz-ip
1. 职责
把「IP → 城市」和「城市编码 → 城市信息」两件事封装成静态工具:IPUtils.getArea(ip) 给出 IP 归属地,AreaUtils.getArea(id) / format(id) 给出中国行政区划的层级与全名。
数据随 jar 一起发布:area.csv(行政区划表)与 ip2region.xdb(IP 库),启动时一次性加载进内存,查询不走网络。
它不解决:IP 库的热更新(换库要重新打包)、经纬度与地理围栏(只有行政区划树)、国外城市的中文名(依赖 area.csv 的覆盖范围)。
本节路径均省略公共前缀
framework/pmforge-spring-boot-starter-biz-ip/src/main/java/com/pmforge/framework/。
2. 关键类
| 类 | 作用 | 路径 |
|---|---|---|
Area | 行政区划节点:id、name、type、parent、children;常量 ID_GLOBAL=0、ID_CHINA=1 | ip/core/Area.java |
AreaTypeEnum | COUNTRY(1)、PROVINCE(2)、CITY(3)、DISTRICT(4),实现 ArrayValuable<Integer> | ip/core/enums/AreaTypeEnum.java |
AreaUtils | 读 area.csv 建树;getArea(id)、parseArea("河南省/石家庄市/新华区")、format(id)、getByType(...)、getParentIdByType(...) | ip/core/utils/AreaUtils.java |
IPUtils | 读 ip2region.xdb;getAreaId(ip)、getArea(ip)、getAreaId(long ip) | ip/core/utils/IPUtils.java |
area.csv / ip2region.xdb | 行政区划与 IP 库,随 jar 发布 | src/main/resources/ |
AreaUtilsTest / IPUtilsTest | 两个工具类的单测 | src/test/java/com/pmforge/framework/ip/core/utils/ |
3. 自动配置
| 配置类 | 生效条件 | 注册了什么 |
|---|---|---|
| 无 | — | 模块没有 AutoConfiguration.imports,也没有 @Configuration;两个工具类都是 @UtilityClass + static {} 初始化 |
因此它在运行时是「零装配成本」的:任何模块只要依赖了它,AreaUtils.getArea(...) 直接可用;代价是初始化发生在类第一次被加载时。
4. 配置项
| 前缀 | 键 | 默认值 | 说明 |
|---|---|---|---|
| — | 无 | — | 没有 @ConfigurationProperties,资源文件名与路径都是常量 |
写死的资源与约束:
| 项 | 值 | 出处 |
|---|---|---|
| 行政区划数据 | area.csv(无表头,列含 parentId) | AreaUtils 静态块 |
| IP 库 | ip2region.xdb | IPUtils 静态块 |
| 层级深度 | AreaTypeEnum.values().length(4) | AreaUtils.format 的防死循环上限 |
5. 扩展点
- Excel 导入导出地区:
AreaConvert用AreaUtils.parseArea(label)把「河南省/郑州市」转成Area.id存库。 - 展示全名:
AreaUtils.format(id)默认-连接、自动省略「中国」节点;自定义分隔符用format(id, "/")。 - 按类型取同级/父级:
getParentIdByType(id, AreaTypeEnum.PROVINCE)、getByType(PROVINCE, Area::getId)。 - 换 IP 库:只能替换
ip2region.xdb资源并重新打包,没有运行期刷新入口。 - 换行政区划数据:替换
area.csv,但必须保持列顺序与 parentId 结构,否则静态块抛RuntimeException("AreaUtils 初始化失败", e)。
6. 常见坑
xdb里存的是「area id」而不是官方的「国家|区域|省份|城市|ISP」:IPUtils.getAreaId直接Integer.parseInt(SEARCHER.search(ip)),换回 ip2region 官方完整库会抛NumberFormatException。- 失败发生在类加载时,且不可恢复:静态块里
throw new RuntimeException("IPUtils 初始化失败", e),一旦 jar 里的资源缺失,第一次调用就会ExceptionInInitializerError,之后该类在这个 JVM 里永远是失败状态。 - 内网/非法 IP 不会返回
null:ip2region对查不到的地址返回0,而ID_GLOBAL恰好是0,会被映射成「全球」节点;判空逻辑要按 id 判断,不能只判null。 parseArea用中文名逐级匹配:输入必须是「省/市/区」的完整路径且分隔符为/,重名区县(如多个「新华区」)靠上级路径区分,只写区名会解析失败。Area的parent/children是双向引用:类上@JsonIgnoreProperties/@JsonManagedReference/@JsonBackReference已处理序列化,但自己写equals/hashCode或日志打印时要避开,否则栈溢出(@ToString已排除parent)。
7. 关联页面
- starter-excel:
AreaConvert的唯一使用方 - pmforge-common:
ArrayValuable等基础类型 - 地区管理、横切机制、枚举字典