问题3. 地址使用规范

使用地址库jar包,请严格遵循下面的规范,这会让你的代码保持很好的健壮性,在区划变动或者升级的时候不至于出问题,一劳永逸;如果确有业务场景在此规范之外,可以联系地址库团队review。规范的核心是“以id为准,使用name要慎重”。

  1. 以id为key保存行政区划(而不是name),例如“浙江省-杭州市-余杭区”,可以保存余杭区的id 330100,在读取的时候通过jar包解析出完整的区划名字链。这个规范主要是基于行政区划名字是经常变化的,但地址库会确保id的稳定性。

  2. 系统间使用id交互(而不是name),系统传参、提供二方库、前端页面返回选择的区划,都使用id,例如“checkRegion(Long divisionId)”,不要定义诸如“checkRegion(String provName, String cityName)”之类的方法。这个规范的理由同1。

  3. 禁止使用字符串比较或者equals判定行政区划是否相等,例如“provName.equals(division.getProv())”,如果业务确有需要,可以使用common-division包提供的方法。这个规范主要基于三点,一是name的易变性,name不同的区划可能是相等的(新老);二是存在同名name,三是同一区划的name有不同的表现形式(全称、简称、别称)。

  4. 区划id类型为Long,还在使用int类型的老应用,在国际化或者5级之后,会出现问题,请尽快升级为Long。

  5. 禁止使用id数值进行区划类型判断,id长度、结尾、取值范围等都不适用,测试代码和临时性的数据分析可以不受此限制。

  6. 使用divisionLevel判定区划级别,divisionLevel是区划级别的唯一规约,不要使用写死追溯叶子节点或者根节点的方式,诸如“1 == area.getParentDivision().getParentDivision().getParentDivision().getDivisionId()”,写死4次getParent,这种方式的误区是在跳级的时候可能出现错误,例如“湖北省-天门市-竟陵街道”,可能会将4级地址“竟陵街道”误判为3级区划,或者空指针。

  7. 跳级区域的处理方式,同一系统内部保持一致,对外使用id交互,例如app A将“天门市”作为地级市处理,app B将“天门市”作为区处理,在使用id交互的前提下,不会出现问题,B可以根据id读取和重新拼接区划,A的处理方式对B是透明的;如果使用name,那么就会出现对接不上的情况。

  8. 使用UIC的地址,根据id重新拼接,不要直接使用UIC保存的省市区名字,具体参考UIC地址使用规范,这个规范可以推及到所有需要读取其它db数据的地方,例如卖家地址库。这个规范主要是消除名字不一致或者区划name过老导致的数据不一致。

  9. 部分API的使用规范参考“common-division健壮性升级指南”。