Java 收货地址解析实战一条乱地址如何被拆成姓名、手机号和省市区44 条真实样本验证【免费下载链接】address-parseJava 版智能解析收货地址项目地址: https://gitcode.com/gh_mirrors/addr/address-parse去年有段时间我负责维护公司的订单后台最头疼的活就是把用户填的收货地址整理进数据库。电商订单里的地址五花八门太阳鲜鲜 盐田区山海四季城F栋17A13111111111、收货人: 杨燕艳\n手机号码: 13111111111\n所在地区: 广东省深圳市龙岗区龙岗街道、湛江市廉江市车板镇人才市场0755-22107333.曹建林 邮编713200。姓名、电话、省市区、详细地址全挤在一段字符串里格式还各不相同。我先后试过手写正则、找人标数据折腾了一周也没能覆盖所有情况。直到同事甩给我一个叫address-parse的开源项目——一个 Java 版的收货地址智能解析库这个问题才算真正解决。这篇文章就记录我把它接入项目、读源码、踩边界的全过程如果你也在处理类似的地址数据应该用得上。先看它一行调用能输出什么再决定要不要往下读我不喜欢先听一堆特性介绍直接看结果最实在。address-parse 的核心入口只有一个静态方法AddressParse.parse()传进去一段原始地址返回一个ParseResult列表String address 太阳鲜鲜 盐田区山海四季城F栋17A13111111111; ListParseResult results AddressParse.parse(address);上面那条姓名在开头、省略了省市的地址解析结果是姓名太阳鲜鲜手机13111111111省广东省市深圳市区盐田区详细地址山海四季城F栋17A注意一个细节原始字符串里根本没有广东省深圳市这几个字只有盐田区。它靠区名反查行政区划数据把省市区补全了。这正是智能二字的体现。项目自带的测试类AddressParseTest里准备了 44 条真实业务样本覆盖姓名在前在后、带座机、带邮编、换行分段、86 前缀国际号码、直辖市、县级市等各种情况我建议你接手这个库后第一件事就是跑一遍这些用例直观感受它的能力和边界。智能是怎么实现的三级降级策略和一张行政区划树只停留在好用层面是不够的我翻了一遍源码发现它的思路其实很朴素先洗数据再逐层匹配行政区划。整个流程可以分成四步都在AddressParse.parse()里串起来地址清洗把换行、制表符、多余空格压平去掉收货人联系电话所在地区这类冗余关键词再清掉逗号、括号等特殊符号。提取联系方式用正则依次抽走手机号、座机号、邮编并把它们从地址里删除避免干扰后续匹配。提取姓名剩下的字符串按空格切分取显示宽度最长的那一段作为姓名——因为中文地址里人名通常是宽度最突出的部分。匹配省市区这是核心也就是所谓的三级降级策略。第三步的具体做法值得一提。它按省→市→区的顺序做正向解析同时用市→区区做逆向解析最终合并结果。什么叫降级parseByProvince、parseByCity、parseByArea这三个方法分别从省级、市级、区县级出发去匹配优先尝试区县级匹配信息最精确匹配不到就退到市级再不行就省级兜底。所以像盐田区山海四季城F栋17A这种省略了省市县的地址能通过区名反向定位出广东省深圳市。支撑这套匹配的是AreaTree这个树形结构——34 个省级行政区、333 个地级市、2844 个县级区域数据来自src/main/resources/address-parse/china-area.json启动时加载进内存并构造成树。因为节点之间有parent和children指针解析器才能从盐田区一路向上找到深圳市广东省。顺带一提类里有一行日志地址解析器初始化耗时440 ms。初始化只做一次之后每次解析都是纯内存操作44 条样本整体跑完约 100 毫秒出头平均每条地址 2 到 3 毫秒放到高并发接口里完全够用。一个地址返回多个结果用 type 字段做选择第一次跑测试的人大概率会愣一下为什么一条地址解析出 3 条结果看测试输出比如谢先生深圳市龙岗区南湾街道尚峰花园4C2231 13111111111同时返回了类型CITY和类型AREA两条记录内容几乎一样。这是因为三级策略都命中了每条结果分别代表从不同层级切入得到的结论。ParseResult里有个type字段取值PROVINCE/CITY/DISTRICT标注了这条结果的来源层级。实际使用时通常按区县级 市级 省级的优先级取第一条或者直接调format()把结果拼成易读字符串再人工校验。ListParseResult results AddressParse.parse(address); if (!results.isEmpty()) { ParseResult best results.get(0); // 一般第一条最精确具体取哪条视业务而定 }另外注意极少数情况下不同层级会给出冲突的结果。测试输出里有个典型例子湖北省黄石市牧羊湖水机路华瑞南岸星城被市级解析正确识别为湖北省黄石市而逆向的区级解析却误判成重庆/南岸区——因为南岸这个词恰好是重庆的一个区名。代码里针对同省地区匹配错误做了专门处理但这类歧义在纯文本解析里无法 100% 消除所以我建议线上系统把返回结果记录到日志方便定期复盘调优。把它接进项目依赖和最小代码接入成本低到可以忽略。项目基于 MavenJDK 8 即可依赖了 Guava、Hutool、Apache Commons 这些常见库pom.xml已经全部配好。克隆下来后git clone https://gitcode.com/gh_mirrors/addr/address-parse之后引入核心类就能用不需要额外初始化。上面那段调用就是全部代码。如果想把选最准确结果的逻辑做得稳健一点可以包一层安全方法解析失败或结果为空时记日志、返回默认值避免异常直接打到业务层。解析不准时官方给你留了三扇后门没有任何解析库能覆盖所有脏数据好在 address-parse 在可扩展性上留了余地一是扩充屏蔽关键词。AddressParse.EXCLUDE_KEYS是个公开的静态列表默认已经包含收货人联系电话详细地址等常见词你可以往里面追加自己业务里出现的冗余词。二是自定义行政区划。行政数据在AreaTree里以标准树结构组织字段包括行政代码、邮政编码、区号、全名和简称。如果业务涉及特殊区域或行政区划调整可以按同样结构修改china-area.json后重新打包。三是结果校验兜底。比如必须有手机号、必须有详细地址这类业务校验写在解析之后信息不全的地址转入人工审核队列。解析器负责把文本拆开业务负责判断拆得对不对各司其职。诚实地说它适合什么场景又替代不了什么用了两个月后我给它画了个使用边界免得大家预期过高适合的电商订单、物流运单、用户资料清洗这类需要把混在一起的姓名、电话、地址拆开且省市区要尽量标准化的场景。它是纯本地运行不需要网络请求数据不出内网也没有按次计费的 API 成本性能和价格上都适合批量处理。不适合的它只识别到区县级AreaEnum里虽然定义了乡镇TOWN和村VILLAGE两个层级但解析并不会再往下细分。所以龙岗街道格水村三巷十号三楼里的街道村巷会原样留在详细地址里。另外对于极端歧义文本上文提到的跨省区名撞车它偶尔会给错答案需要业务层做二次校验。对比手写正则正则只能解决格式固定的地址遇到姓名在中间缺省市带冗余标签就崩对比第三方地址解析 API那个有网络依赖和费用而且数据要出内网。address-parse 正好填补了本地、免费、够用这个空档。从手工抄单到自动入库的最后一公里回到开头那个订单后台。接入 address-parse 后我做的事从人肉拆地址变成了解析结果 人工复核异常单处理效率提升了一个量级邮编、座机、手机号都自动归位省市区信息也统一了格式。它没有魔法就是用三级降级匹配加完整的行政区划数据把大部分脏地址处理在了程序里。如果你也在写 Java也正被收货地址数据折磨不妨按上面的步骤把它跑起来。先把项目里的AddressParseTest完整看一遍——那 44 条真实样本就是最好的使用文档。【免费下载链接】address-parseJava 版智能解析收货地址项目地址: https://gitcode.com/gh_mirrors/addr/address-parse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考