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