开发笔记:万万没想到一个普通的地区问题，竟然让我们大战了300回合

前言

我最近参与了公司的一个新项目&＃xff0c;需要通过openapi接口把接入方的数据&＃xff0c;比如&＃xff1a;企业、订单、合同、物流等&＃xff0c;同步到我们平台&＃xff0c;然后我们平台给他们提供金融能力。

由于我方跟对接方不在同一个城市&＃xff0c;为了提高工作效率&＃xff0c;双方进行了多次在线视频沟通。刚开始比较顺利&＃xff0c;没想到在沟通企业信息上传接口时&＃xff0c;接口文档中有个非常不起眼的企业注册地id字段&＃xff0c;让我们一下子进入了僵局。

到底是怎么回事呢&＃xff1f;

1.地区问题

在我们平台的企业表中有一个企业注册地id字段&＃xff0c;是必填的&＃xff0c;用户在注册企业的页面需要选择一个地区&＃xff0c;作为该企业的注册地&＃xff0c;实际上数据库保存的是地区的id。

如果该企业注册成功了&＃xff0c;会在企业详情页面上展示该地区名称。当然我们系统的后台逻辑是先通过地区id到地区表反查出地区名称&＃xff0c;然后在用户界面中展示出来。

为了跟企业表保持一致&＃xff0c;我方在定义接口文档时&＃xff0c;企业注册地id字段也做成必填了。

当时的情况是这样的&＃xff1a;我方地区表中有id、地区名称、国标码、等级等字段&＃xff0c;但这里的id&＃xff0c;是我方数据库的主键&＃xff0c;对接方系统中肯定是没有的。对接方系统中也有一套地区表&＃xff0c;不过id是他们的数据库id&＃xff0c;他们的表中也有地区名称、国标码、等级等字段。

所以他们系统内部需要经过一番转换&＃xff0c;才能把我们所需的地区id传给我们。

1.1 持久化本地地区表

其实这个项目我是中途才加入的&＃xff0c;之前在处理别的事情&＃xff0c;我加入的时候接口文档已经定义好了。

我方跟对接方进行第二次在线沟通的时候&＃xff0c;双方一起过接口文档的细节&＃xff0c;包括&＃xff1a;接口的作用、每个参数的含义&＃xff0c;以及他们是否有值传过来等等。

其中过到企业信息上传接口时&＃xff0c;接口文档中有个企业注册地id字段&＃xff0c;对方没法传值过来。为了解决这个问题&＃xff0c;我方第一版的方案是&＃xff1a;

1. 对接方调用我方地区查询接口&＃xff0c;通过多次分页查询&＃xff0c;最终能获取我方所有地区数据&＃xff0c;落库到他们本地的地区表。
2. 他们在调用我方企业信息上传接口之前&＃xff0c;先查询本地的地区表&＃xff0c;转换成我方所需要的地区id。

在讨论的过程中&＃xff0c;对接方觉得他们也是平台&＃xff0c;不应该做这些额外的事情。所以在那次会议中&＃xff0c;双方针对这个问题&＃xff0c;谁也没有说服谁&＃xff0c;最终也没能达成共识。

后来&＃xff0c;我思考了一下&＃xff0c;确实这个方案太过理想化了&＃xff0c;没有真正站到用户的角度思考问题&＃xff0c;忽略了很多细节。可能跟文档设计者不对地区表不太熟悉有关系。

1.2 按名称调用地区查询接口

那次会议当中&＃xff0c;我们这边的几位同事&＃xff0c;短暂的讨论了一下。既然对接方不愿意接受在他们本地持久化地区表&＃xff0c;我们就退而求其次&＃xff0c;不要求他们持久化了。这时我们这边有个同事提出&＃xff0c;改成按名称调用地区查询接口&＃xff0c;反查出地区id&＃xff0c;具体方案如下&＃xff1a;

这个方案表面上看起来没有问题&＃xff0c;但我之前负责过区域相关功能&＃xff0c;我知道&＃xff0c;就怕出现如下情况&＃xff1a;

1. 如果对接方传的地区名称不完整&＃xff0c;比如&＃xff1a;本来是成都市&＃xff0c;实际上传的成都。这样&＃xff0c;我们地区查询接口&＃xff0c;需要做模糊匹配&＃xff0c;如果并发调用接口可能影响接口性能。
2. 如果输入关键字北京市&＃xff0c;在我们这边的地区表中&＃xff0c;可以找到两条数据&＃xff0c;一条是跟省级别一样的&＃xff0c;另一条是跟市级别一样的。到底对应哪条数据呢&＃xff1f;

所以我当时把这两个问题抛出来了&＃xff0c;不建议使用地区名称查询。

1.3 按国标码调用地区查询接口

那个同事听完之后&＃xff0c;也觉得用地区名称查询有点不靠谱。他马上修改方案&＃xff0c;改成使用地区的国标码查询地区id&＃xff0c;具体方案如下&＃xff1a;

由于当时讨论时间非常短&＃xff0c;我们没来得及考虑太多&＃xff0c;暂且打算用这套方案。

1.4 企业上传接口入参传国标码

过了一会儿&＃xff0c;双方继续过接口文档&＃xff0c;重新讨论企业信息上传接口中企业注册地id字段传值问题。

他们在调企业信息上传接口之前&＃xff0c;先调一下我们地区查询接口&＃xff0c;查出地区id&＃xff0c;入参是国标码。然后再将这个地区id&＃xff0c;在企业信息上传接口中传过来。

对接方仔细听了我们的方案&＃xff0c;犹豫了一下&＃xff0c;他们觉得没有必要再调一次地区查询接口&＃xff0c;双方都使用国标码不就行了&＃xff1f;

他们的想法是&＃xff1a;在企业信息上传接口中&＃xff0c;入参由企业注册地id改成企业注册地国标码&＃xff0c;由于国标码是国家统一的唯一编码&＃xff0c;双方肯定是一样&＃xff0c;能保证数据的一致性。

2.想起了一个问题

说实话&＃xff0c;如果你没接触过地区功能的话&＃xff0c;大部分人可能会同意这套方案的。

但比较巧合的是我之前正好接触过类似的功能&＃xff0c;当时我突然想起了一个问题&＃xff1a;双方数据的一致性如何保证&＃xff1f;

我们都知道&＃xff0c;由于国家的发展&＃xff0c;有些城市可能会改名&＃xff0c;比如&＃xff1a;襄樊改成了襄阳&＃xff0c;另外有时候多个地级市合并成一个市&＃xff0c;这样国标码会变化&＃xff0c;所以国家统计网每年都会调整地区名称和国标码。

我方的地区表是两年之前创建的&＃xff0c;数据初始化好之后没有就更新过。

而对接方不是跟我们在同一时刻初始化的数据&＃xff0c;而且他们会定期更新地区数据&＃xff0c;这样就导致了两边的数据不一致。如果对接方的业务表单中使用了新加的城市名和国标码&＃xff0c;而这些信息在我方的地区表中没有&＃xff0c;就无法查询出我方所需的地区id。

这种情况该怎么办&＃xff1f;

2.1 双方同一时刻更新地区表

显然上面的问题是一个非常棘手的问题&＃xff0c;这时候有些小伙伴可能会说&＃xff1a;双方使用job同一时刻更新地区表&＃xff0c;不就能解决问题了&＃xff1f;

我不太赞成这种方案&＃xff0c;主要原因如下&＃xff1a;

1. 我方仅跟这个对接方有个同步执行的job&＃xff0c;没问题。但如果还有其他的对接方&＃xff0c;也需要调用企业信息上传接口&＃xff0c;是不是也要整一个job&＃xff0c;而且还要求大家都同一时刻执行&＃xff0c;耦合性太大了。
2. 如果我方和对接方同时执行job&＃xff0c;但万一有任意一方执行失败了&＃xff0c;也会导致数据不一致的情况。如果恰好这时候对接方在调用企业信息上传接口&＃xff0c;会不会出问题&＃xff1f;

2.2 以一方的地区数据为准&＃xff1f;

上面的双方同一时刻更新地区表的方案确实有点不靠谱&＃xff0c;但有些读者可能会问&＃xff0c;以一方的地区数据为准&＃xff0c;另一方把数据同步过来不就行了。具体方案如下&＃xff1a;

这个方案其实跟之前我方给出的第一个方案很相似&＃xff0c;已经被对接方拒绝了。站在他们的角度来说&＃xff0c;确实没有必要因为上传企业信息&＃xff0c;而保存我们的地区数据。

说实话&＃xff0c;即使他们同意了&＃xff0c;这种跨公司跨系统的数据一致性问题&＃xff0c;也不好保证&＃xff0c;因为如果对接方调用我们的地区接口失败了&＃xff0c;此时&＃xff0c;正好在上传企业信息&＃xff0c;是不是也有问题&＃xff1f;

我们一下子进入了困境&＃xff0c;但为了不影响整体进度&＃xff0c;只能先记录一下问题&＃xff0c;然后跳过这个问题&＃xff0c;继续讨论其他字段了。

3.如何解决这个问题&＃xff1f;

我当天晚上思考了良久&＃xff0c;第二天早上&＃xff0c;发现跟我们老大的想法不谋而合。得出的结论是&＃xff0c;既然存在差异化&＃xff0c;没办法避免&＃xff0c;我们就要从系统设计上接受差异化。在企业信息上传接口中增加两个字段&＃xff1a;企业注册地国标码 和 地区名称&＃xff0c;对接方改成传入这两个字段&＃xff0c;具体方案如下&＃xff1a;

1. 在我方的企业表中增加地区名称字段&＃xff0c;是非必填的&＃xff0c;同时把之前的地区id字段也改成非必填。
2. 对接方在调用我方企业信息上传接口时&＃xff0c;同时传入地区国标码和地区名称。
3. 我方企业信息上传接口中判断&＃xff0c;如果通过国标码能够找到地区id&＃xff0c;则将地区id写入db&＃xff0c;如果找不到&＃xff0c;则将地区名称写入db。

我们评估了一下影响范围&＃xff0c;在企业表中的地区字段&＃xff0c;只做展示用&＃xff0c;没有修改入口&＃xff0c;所以上面的这套方案是可行的。

后来&＃xff0c;再次跟对接方在线沟通时&＃xff0c;把我们的这套方案告诉他们了&＃xff0c;他们非常赞同。

4 总结

虽说这个地区问题&＃xff0c;在众多技术问题中不值得一提。但是我仔细思考了一下&＃xff0c;还是有一些宝贵的经验值得总结一下的&＃xff0c;给有需要的小伙伴一个参考。

4.1 要从用户的角度设计接口

在设计接口文档时&＃xff0c;要真正做到从用户的角度出发。

尤其是像这种openapi接口&＃xff0c;定义的参数应该尽量选择通用的&＃xff0c;大家都认可的参数&＃xff0c;避免出现我方定制化的参数&＃xff0c;比如&＃xff1a;地区id。

尽量减少用户的复杂度&＃xff0c;让他们调用接口时更简单一些。

4.2 技术方案要有包容性

技术方案要有包容性&＃xff0c;不是非黑即白&＃xff0c;需要有柔性的思想。在分布式环境中&＃xff0c;如果去一味地追求数据的强一致性&＃xff0c;不会有太好的结果。就像高并发下的商品秒杀系统&＃xff0c;如果非要用同步方案去实现&＃xff0c;系统最终可能会挂掉&＃xff0c;更好的方案其实是改成异步队列处理。

我方和对接方都有地区表&＃xff0c;数据很难保证完全一致&＃xff0c;我们不要为了一致性而一致性&＃xff0c;这样会适得其反。为了工作能够顺利进行下去&＃xff0c;必然有一方要妥协&＃xff0c;我的建议是openapi接口方做妥协&＃xff0c;这种技术方案才够通用。

4.3 没有最好的方案&＃xff0c;只有最适合的

我方最后的那个方案&＃xff0c;其实并没有完全解决地区id找不到的问题&＃xff0c;但是从业务的角度来看&＃xff0c;即使没有地区id&＃xff0c;有地区名称也是一样的。很显然&＃xff0c;最后的方案是非常适合我们实际业务场景的。

所以没有最好的方案&＃xff0c;只有最适合业务场景的。

4.4 进行有效的沟通

在跟对接方在线沟通时&＃xff0c;不要因为某个问题卡壳了&＃xff0c;而一直僵持下去。如果当时没有好的技术方案&＃xff0c;可以先选择暂时跳过这个问题&＃xff0c;而沟通其他的内容。后面我们再私下单独花时间&＃xff0c;仔细思考当时的问题&＃xff0c;从而能够提出更合理的方案。