4个真实案例，看接口文档的设计要点.docVIP

4个真实案例，看接口文档的设计要点 接上一篇文章《 \t /pd/_blank 4个要点，编写一份接口需求文档》，本文对工作中做过的实例进行分析，希望通过实例能对接口设计需要考虑的因素有更深的理解。 案例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. 需求背景 需求生成