关于接口开发和联调的一些感想

Posted 2020-11-17 hhelibeb

最近项目上在做销售订单、预付款申请、贸易合同传输OA审批等功能，也经历到了自己遇到过的最糟糕的接口联调。SAP与泛微OA之间的对接有比较成熟的方案，我们的工作过程不顺利，终究是人的原因。我想把自己的一些看法记录下来，留作教训。

内部名还是外部名？

不同系统间的接口开发工作中的一个难点是接口提供者和被调用者对接口的不同理解。同样的一个概念，在不同系统中可能有不同的名称；同样的一个名词，在不同系统中又有可能有着不同的意义。在理想情况下，确定接口字段的定义和描述的人，应当对两个系统的领域语言有所了解，有能力找到其中的相同与不同点，并且在相关的文档中做出准确的表述，让双方的参与人员理解自己的意图。

在现行的接口开发流程下，通常会由SAP业务顾问和对接系统的相关负责人来确定接口字段的名称和意义，而SAP业务顾问在这当中又起着主导性的作用。实际上，SAP业务顾问有着丰富的业务和系统知识，理论上是有能力处理好相关工作的。但在实践当中，不少业务顾问似乎对自己的工作还没有足够的认识，因此人们看到的文档是类似这样的：

假如读者是熟悉SAP系统的人，可能会知道：SUPERFIELD是采购订单相关事务屏幕中的一个抬头字段，它时而对应供应商，时而对应工厂等内容；NAME2，NAME3来自于NAME1，它是SAP系统主数据表中的常见字段名，意为名称；BUKRS大概来自于“公司代码”的德文写法，也是SAP系统中公司代码的技术名称。

这样的文档，即便目标人群是SAP系统的开发者，也不是完全合适。比如供应商在SAP中的技术名称通常是LIFNR，所谓SUPERFIELD，是一个意义不明的通用名称，容易给读者带来困惑。

而在SAP与非SAP接口的开发中，这样的文档是不太合格的。显然一个非SAP系统的技术人员，没有义务懂得SUPERFIELD和BUKRS的名字来源，因此在接口中应当使用字段的外部名，而非内部名。如果要传递正确的信息给人们，尽量减少误解，应该采用如下的比较合理的定义方式：

一个有经验的SAP开发者十分清楚VENDOR即SAP中的LFA1-LIFNR，COMPANY即T001-BUKRS。一个非SAP系统的开发者大概也能看懂这几个词的意思。这样一来，产生误会的可能性就降低了，思考的负担也降低了。因为没有人需要再死记硬背“NAME3”的含义。

 

名与实

“名不符实”是全社会共同面对着的难题，在开发工作中也不例外。我开发的某个接口中存在一个字段NETWR1，本来的意义是“净值”（Net Value），在一次口头需求变更后，它变成了“总值”（Gross Value），但接口文档依然保持着如下模样：

我很希望文档的撰写者可以对它的字段名、描述、长度做出合理的修改，也对她做出了建议。但是我的希望最终被忽视了，理由是工期紧，并且我“没有准确理解需求”。

需求文档是人们理解系统中自定义业务逻辑的重要依据，如果需求文档中存在大量的名不符实的东西，那么一段时间过去后人们只能从代码中考古，理解前人的工作了。

比较有趣的是，最不喜欢撰写可靠文档的人，同时也往往是最喜欢要求“来个开发，帮我debugger一段代码，看看这些程序到底在做什么”的人。从这个角度看，他们无愧是提高ABAP开发人员就业率的功臣...

联调的前提

良好的工作流程和良好的的程序程序一样，可以清晰的让人明白何时开始、何时结束。

这里的“时”指的应当是时机和非时间，即它不是一个单纯的时间点，而是一个结合了条件的时间点...

在接口联调的工作里，我认为，存在一个基本的前提条件，那就是接口已经通过测试。

接口联调的重要目的是发现问题、解决问题。解决问题的前提是定位问题，而定位问题的区域范围越小，就越容易用较小的成本解决问题。

如果接口联调时，双方的程序都处于一种极为不确定的状态，那么联调中一定会暴露大量问题，且需要密切和低效率的沟通来确定问题发生在哪一方。两个不确定的程序交织在一起。而这两份不确定，又给整个联调带来了更多额外的不确定..本来是用于调试接口本身的问题的时间，可能会变成天马行空找bug的过程占用。

在这个项目当中，有的接口开发人员甚至没有使用Postman或者SoapUI之类的工具对自己的接口做最基本的测试，而调用接口的代码，在联调时居然常常没有完成，需要现场编写..编写时又发现提供的接口与文档不一致等情况。令人无言已对。

等待时做什么

联调时会出现一种现象：一个人在改刚刚发现的问题，其它人则进入“事不关己”状态，开始聊天玩手机或者做其它工作。我觉得这不是一个有益的现象。

在进入这样的状态之前，建议先按以下顺序做检查：

1. 发现的问题是否和接口联调有关，在不影响联调的前提下，可不可以将它记录到问题清单中，事后再改？
2. 在其它人做修改的时候，自己和其它参与联调但不需要改东西的人可不可以进行一些异步的工作，比如为联调中的下一项小工作做准备？
3. 能不能用电脑代替手机，来做自己想做的事情？

九个人等待一个人工作是一种低效的工作方式，而智能手机的出现甚至可能会降低那唯一一人的工作效率，让大家等待更久的时间。（参考 智能手机如何绑架了我们的大脑，华尔街日报）。因此要尽量避免这种情况发生。