如何设计接口文档？案例剖析接口设计文档的要点

案例1

1. 需求背景

SRM系统的用户，需要在SRM查看自己提供的商品的质检情况；但是质检的数据在商品管理系统中，故需要SRM从商品管理系统获取对应的数据

2. 需求设计

需求关键点是SRM需要从商品管理系统获取数据并展示给自己用户，实现这一点有两种方式：

（1）SRM固定频次从商品管理系统获取

选择这种方式，有一个绕不开的问题：什么时候去取数据合适？普遍的自然就想到按固定的频率，那么这个频率应该是什么？

考虑到用户随时都会点击查看，半小时、一小时的频率肯定不行；实时性应该越高越好，那半分钟或者1分钟取一次呢？

这样做相比半小时实时性高了很多，但考虑到数据量的因素，虽然每分钟会去获取，但是获取到数据后进行合法性校验、完了组装存储，整个周期就远不是1分钟了，有可能用户点击的时候，数据刚获取到，还没处理完存储到表中，故也无法展示；

同时，随着数据量增大，此种情况下很容易出现漏数据和数据重复的情况，数据量太大，程序执行时间过长而自动停止，导致数据遗漏，第一次还没处理完，第二次已经开始了，结果相同的数据多次写入，导致数据重复。

故此种方式不可行。

（2）商品管理系统主动同步

既然自己取不可行，那么商品管理系统主动将数据同步到SRM呢？

当商品管理系统的质检信息有变更时，主动将数据同步给SRM，用户在SRM查看的时候，SRM从自己的表中获取数据并展示，这样看这种方案是完全能够满足要求的。

我一开始做的时候，也是选择的这种方案，但是在与开发沟通的时候（一般做接口更偏向技术，所以我都事先会跟开发私下讨论一下），发现有一个问题：相同的信息有没有必要在两个系统存储两份？因为质检信息中存在附件文件，文件很占存储空间。是否有更好的方案来避免这个缺陷？

结合上面这两个分析，我们知道这个接口有两个点很重要：

实时性要求极高；能共用一份信息就不存两份。基于实时性要求高这个点，为什么不做成用户查看的时候，实时去商品管理系统获取数据并展示出来呢？这样也解决了SRM不用存储冗余信息的问题。

为此此需求最佳的方案是：当用户在SRM点击查看的时候，SRM实时去商品管理系统获取质检信息并展示，无需本地保存：

PS：实时获取有一个隐形的问题是：并发。若并发量高，实时获取的方式不可取。但此业务中，并发可能性低，所以此方案可行最优。

案例2

1. 需求背景

采购系统需要给预测服务同步产品的未成功订货的数量，以方便预测服务预测后期的采购量；采购量的预测每天一次，每天凌晨开始。

2. 需求设计

因为采购量每天算一次，所以在计算前将数据同步过去即可，实时性要求不高；因为整个预测过程需要大量的计算，预测系统必须存储数据方便计算，不可能计算到的时候再来取数据，并且不是文件数据，占用存储空间小，所以此数据预测系统必须存储；因预测服务需要的是全量的数据，不用一个个带着参数来获取数据。因此接口可设计如下：

从表面上看，这个接口设计没有问题，完全满足需要。

但是忽略的一个问题是：因为双方没有明确约定数据更新方式，导致两边数据对不上出了bug。

很明显，同步方是以全量的方式同步数据的，但是接收方在接收数据的时候，却是以增量的方式更新的。

当一个产品前一天同步的未订数量是34，第二天这个数量更新成了0的时候，接收方没有将34更新成0，存的还是34。

案例3

1. 需求背景

客服系统需要根据客户的要求，向商品的供应商索取商品操作指南等辅助信息；因为客服系统没有供应商信息，故需要从SRM系统获取供应商信息；已停止合作的供应商应排除掉；供应商需要产品对应。

2. 需求设计

（1）考虑到客服系统对状态有要求，为了更加灵活，我将接口设计如下：

这样的设计有个很大的问题是，供应商的状态客服系统并没有。假如在预先实现时，根据现有状态值双方约定好，但随着SRM系统的发展，当供应商的状态值变更或新增时，存在两边数据不一致和获取不到数据的隐患，所以这样的设计不能不说容错性是很低的。

（2）既然客服系统没有状态值，那它只根据商品编码来获取，我将供应商及其状态都返回给它不就可以了，为此我的第二版设计是这样的：

这样的设计其实跟第一版有同样的问题，即使将状态返回给它，它因为不知道这些状态的业务意义，也就无法过滤掉那些没用的数据只给客服人员展示有效的信息。

（3）经过两版分析，我的第三版设计如下：

此次的设计解决了前两次的问题，但是没有考虑异常情况：没有满足条件的数据时，要返回什么来告诉对方为什么没有数据？所以接口还需要一个错误信息。

（4）结合以上，最后的设计如下：

案例4

1. 需求背景

需求生成服务需要告诉采购系统采购需求，以让采购系统下采购订单；采购系统对数据的要求根据不同的情况而不同，这里假设：A类需求必须有字段a，B类需求不需要有字段a。

2. 需求设计

一开始设计的文档的时候，我是这样设计校验的：

A类需求没有字段a的时候，返回报错信息“A需求字段a不能为空”；B类需求有字段a的时候，返回报错信息“B需求字段a应该为空”。在与开发沟通的过程中，他们提出：如果B类需求给了字段a，会不会影响后面的流程？

我的回答是：不会，只是这个信息后面流程用不到。

那么当B类需求给了字段a的时候，还是正常接收数据，只是不接收字段a。

这样做的好处是：接口校验少了一层，变得更轻更简单；不会因为一个用不到的信息影响后面的流程。

所以改一下校验逻辑：

A类需求没有字段a的时候，返回报错信息“A需求字段a不能为空”；B类需求有字段a的时候，不接收字段a，但正常接收需要的其他字段。这里涉及到接口设计中的校验，增加校验的目的是，保证相互通讯的数据是正确的，对接收方而言保证自己受到的信息不是垃圾数据或因为错误而影响后面流程。

但是在设计校验规则时，应该有一个强校验还是弱校验更合适的考量。正如上文的接口，A类需求的字段a是后面流程必须用到的信息，所以必须采用强校验；相反B类采用弱校验即可。

PS：诚然，除了这些问题以外，还有主明细方式传输、分页、最大量限制等等的点，最好的方式是在搞清楚业务需求后，及时跟开发同学做下探讨和沟通，听听他们的意见和考量（所以处好关系很重要呀，哈哈）。