Skip to content

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=1ip/core/Area.java
AreaTypeEnumCOUNTRY(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.xdbIPUtils 静态块
层级深度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. 常见坑 ​

  1. xdb 里存的是「area id」而不是官方的「国家|区域|省份|城市|ISP」:IPUtils.getAreaId 直接 Integer.parseInt(SEARCHER.search(ip)),换回 ip2region 官方完整库会抛 NumberFormatException。
  2. 失败发生在类加载时,且不可恢复:静态块里 throw new RuntimeException("IPUtils 初始化失败", e),一旦 jar 里的资源缺失,第一次调用就会 ExceptionInInitializerError,之后该类在这个 JVM 里永远是失败状态。
  3. 内网/非法 IP 不会返回 null:ip2region 对查不到的地址返回 0,而 ID_GLOBAL 恰好是 0,会被映射成「全球」节点;判空逻辑要按 id 判断,不能只判 null。
  4. parseArea 用中文名逐级匹配:输入必须是「省/市/区」的完整路径且分隔符为 /,重名区县(如多个「新华区」)靠上级路径区分,只写区名会解析失败。
  5. Area 的 parent/children 是双向引用:类上 @JsonIgnoreProperties/@JsonManagedReference/@JsonBackReference 已处理序列化,但自己写 equals/hashCode 或日志打印时要避开,否则栈溢出(@ToString 已排除 parent)。

7. 关联页面 ​