一、什么是接口
百科上对接口的定义：API（Application Programming Interface,应用程序编程接口）是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。
要理解接口是什么，首先理解一下为什么要用接口？
两个独立的系统，它们的数据或程序是独立的，这就使得它们无法直接访问对方的数据库或程序（两个独立的数据相当于两个独立的家庭，每个家庭肯定是不允许外人随便进入的，否则会发生偷窃等后果严重的事件）。但是某些业务场景下，独立的系统之间又必须相互共享数据或共用一套程序逻辑，如统一业务流程上的不同业务操作系统，下游系统的业务依赖于上游系统的数据。
既然如此为什么不把它们设计成一个系统，这样不就没有上面的问题了吗？
这是因为有的业务流程很长很复杂，如果设计成一个系统，整个系统变得很庞杂，不论是功能设计、开发维护都很难。因此一般都会把虽然有上下游业务关系但又有清晰边界的业务划分成独立的系统实现，如采购系统和仓储系统。此外，很多时候我们需要获取的数据是我们外部其他公司拥有的数据，更不可能设计成同一个系统了。
基于以上两点：接口就是两个独立系统之间同步数据或访问对方程序的途径。
二、如何设计接口
1. 搞清楚是主动访问还是被动请求：
a. 若是主动访问，有两种情况：
一是我方是数据的使用方，需要主动从对方获取数据；二是我方是数据的提供方，需要主动将数据同步给对方。
主动访问时无需做接口，而是访问对方的接口，要搞清楚的问题是：我们需要在什么节点访问对方的接口？是用户触发某个操作的时候实时去访问？还是没有实时性要求，只是周期性地访问？
若我方是数据的使用方且需要的数据是用户使用某个功能必须的数据，因此必须在用户操作时实时去访问对方的接口获取数据并展示给用户，典型的有我们注册某网站时获取验证码的功能。
若我方是数据的使用方且需要的数据是一些跟用户实时操作无关的基础数据，如客服系统需要从其他业务系统获取用户的基础数据，以在系统中的某些功能下展示用户的信息（如客服在处理客诉等问题时，需要知道客户的一些详细信息，这些信息只有业务系统有）。这种情况下，一般会新增一个脚本定时（如两小时一次）访问对方的接口将数据获取过来存储到自己的数据库，在用到的时候直接从自己数据库获取并展示。
若我方是数据的提供方且提供的数据是下游系统需要的实时要求高的数据则更多地用实时同步；若是基础数据，则选择周期性同步的方式。
b. 若是被动请求，有两种情况：
一是我方是数据提供方，需要对方来获取数据；二是我方是数据使用方，需要对方主动将数据同步过来。
被动请求需要提供接口供对方访问，此时要搞清楚：让对方来访问的时候，需要提供什么样的参数？根据他提供的参数我们需要返回什么数据？这些数据从哪里取值？
若有一些数据的来源是本系统，其他系统需要使用这些数据，则可提供接口让其他系统通过访问接口获取这些数据。
若我方是数据使用方且让对方将数据主动同步过来，此种场景典型如——我们是业务的下游，上游系统产生数据后，需要将数据同步到下游系统让流程继续进行，并且流程的及时性要求高，不能有延迟。这种情况下，只有上游系统知道什么节点产生了数据，因此只有等他产生数据后主动推送给下游系统，因为下游系统因无法知道数据生成的时间，也就无法及时去获取数据，这时最好的方式是让对方主动将数据同步过来。
2. 搞清楚数据交互的实时性要求
a. 对于我方是数据使用方的情况，要根据业务的需要决定获取数据的实时性。
如上文所说，如果是用户使用功能时需要的数据就是即时性访问。如果是定期获取基础数据，根据我们对数据准确性的要求和对方数据变更的频率决定获取的周期。如我们对数据的准确性要求不是100%的要求，且对方的数据变更频率也不是很高，则周期可设计得长一些，如每天一次，每几个小时一次等。
b. 对于我方是数据提供方的情况，则以对方的业务需要为准，但是对于获取数据的访问量大等特殊情况，应在需求中或评审中做好说明和交代，以帮助开发设计更满足需要的接口。
3. 选择合适的接口方式
结合接口的不同类型和实时性要求两方面，可以选择合适的接口实现方式：
a. mq消息队列
是一个中间件，数据提供方将数据放到中间件，数据获取方从中间件中获取数据。针对向多个系统同步基础数据的需要，消息队列是最适合的方式。
若选择这种同步方式，要注意的一点是：增量同步还是全量同步，若是增量同步，对方是增量获取还是全量获取？若是全量同步，在什么情况下，对方应该更新数据，什么情况下应该更新数据？
b. otter同步
数据同步方直接访问数据获取方的数据表将数据写入对应的表中，这种方式实时性最高，若对数据的准确性要求很高，此方式是很好的数据同步方式。
c. http
一般在功能设计中常用的接口是此种方式，双方通过http地址保持数据同步和通信。
在设计具体的数据同步接口时，具体的方式产品经理不用关注，由开发根据需求设计合理的方式，然后产品可帮助开发一起确定所选方式是否满足业务需要。除非业务上有特殊要求，则在需求中可指定具体的方式。
三、如何编写接口文档
不同的接口使用场景，需要关注的点和交代清楚的规则不一样，以主动/被动+数据使用方/数据获取方的维度，有以下四种情况：
1. 如果是向对方系统主动推送数据，则可按以下方式整理接口需求
2. 如果是对方主动来获取数据，则可按以下方式整理接口需求
3. 如果是被动接收对方推送的数据，则可按以下方式整理接口需求
4. 如果主动从对方获取数据，则可按以下方式整理接口需求
PS：在下一篇文章中将以具体的文档实例来说明不同的场景应该考虑和注意的点。书写过程中一些偏技术的点应及时与开发咨询和沟通，防止编写的文档与实际出入太大；接口的开发肯定涉及两个系统，因此在评审前与对方产品对好文档是必须的，要保证双方开发拿到的文档标准是一样的，否则在开发过程中会出现双方约定不一致导致需要修改的情况。
#案例篇#
案例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）既然客服系统没有状态值，那它只根据商品编码来获取，我将供应商及其状态都返回给它不就可以了，为此我的第二版设计是这样的：
这样的设计其实跟第一版有同样的问题，即使将状态返回给它，它因为不知道这些状态的业务意义，也就无法过滤掉那些没用的数据只给客服人员展示有效的信息。
此次的设计解决了前两次的问题，但是没有考虑异常情况：没有满足条件的数据时，要返回什么来告诉对方为什么没有数据？所以接口还需要一个错误信息。
案例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：诚然，除了这些问题以外，还有主明细方式传输、分页、最大量限制等等的点，最好的方式是在搞清楚业务需求后，及时跟开发同学做下探讨和沟通，听听他们的意见和考量（所以处好关系很重要呀，哈哈）。
7641
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
