4个要点,编写一份接口需求文档

1、4 个要点，编写一份接口需求文档在产品设计工作中，或多或少都会需要用到接口，特别是业务导向性的系统，接口几乎是必不可少的功能。那么什么是接口？如何写一份能准确表达业务需求的接口需求呢？百科上为对接口的定义： API（ ApplicationProgrammingInterface, 应用程序编程接口）是一些预 先定义的函数，目的是提供应用程序与开发人员某软件或硬件得以访问一组例程的能力，而又无需访问源码，或理解最高层工作技术细节机制的细节。要理解接口是什么，首先理解一下为什么要用接口？两个独立的系统，它们的数据或程序是独立的，这就使得它们无法直接访问对方的数据库或程序（两个独立数据库相当于两个

2、独立的家庭，每个家庭肯定是不允许外人随便进入的，否则会发生偷窃等后果严重的事件）。但是某些业务场景下，独立的系统之间又必须相互关系相互共享数据或共用一套程序逻辑，如统一业务流程上的不同业务操作系统，下游系统的业务依赖于上游系统的数据。既然如此为什么不把它们设计成一个系统，这样不就没有上面不是的问题了吗？这是因为有的业务流程很长很复杂，如果设计成一个系统内，整个网络系统变得很庞杂，不论是功能设计、开发维护都很难。因此一般都会把虽然有上下游业务关系但又有清晰边界的业务划分成独立的系统实现，如采购系统和仓储系统。此外，很多时候我们需要获取的数据是我们外部其他公司拥有的数据，更为不可能设计成同一个系统

3、了。基于以上两点：接口就是两个独立系统之间电脑系统同步数据或访问对方程序的途径。搞清楚是主动访问还是被动请求：若是主动访问，有两种情况：一是我方是数据的用到方，需要有主动从对方获取数据；二是我方是数据的获取方，需要主动将数据同步给对方。主动访问之前无需做接口，而是访问对方的接口，要搞清楚的问题是：我们需要在什么节点访问对方的接口？是用户触发某个操作的时候实时去访问？还是没有实时性要求，只是周期性地访问？若我方是数据的使用方且能够的数据是用户使用某个功能必须的数据，因此必须在用户操作时实时去访问对方的接口获取数据并展示给用户，典型的有我们注册某网站申领时获取验证码的功能。若我方是数据的使用方且是

4、的数据需要一些跟用户实时操作无关的基础数据，如客服系统需要从其他业务系统获取用户的基础，以在系统的某些功能下展示用户的信息（如客服在处理接线员客诉等问题时，可能需要知道客户的一些表中详细信息，这些信息只有业务子系统有）。这种情况下，一般会新增一个脚本定时（如两小时一次）访问对方的接口将数据获取过来存储到自己的数据库，在用到的时候直接从自己数据库获取并展示。若我方是数据的提供方且提供的数据是下游系统需要有实时要求高的数据则更多地用实时同步；若是基础数据，则选择周期性同步的这种方式。若是被动请求，有两种情况：一是我方是数据直接提供方，需要对方来获取数据；二是我方是数据重复使用方，需要对方主动将数据

5、同步过来。被动请求需要提供接口供对方访问，此时要搞清楚：让假装来访问的时候，需要提供什么样的参数？根据他直接提供的离开参数我们需要返回什么数据？这些数据从哪里取值？若有一些数据的来源是本系统，其他系统需要使用这些数据，则 可提供接口让其他系统通过访问接口获取这些数据。若我方是数据使用方且让对方连动将数据主动同步过来，此种场景典型如我们是业务的下游，上游系统内产生数据后，可能需要 将数据同步到下游系统让流程继续进行，并且流程的及时性要求非常 高，不能有延迟。这种情况下，只有系统知道什么节点产生了数据， 因此只有等他产生数据而后主动推送给下游系统，因为下游因无法知 道数据生成的时间，也就无法及时去

6、获取数据，这时最好的方式是让 对方主动将其要求数据同步过来。搞清楚数据交互的实时性要求对于我方我方是数字使用方的情况，要根据业务的需要决定获取数据的实时性。如上文所说，如果是用户使用功能时需要的数据功用就是即时性访问。如果是定期获取基础数据，根据我们对数据准确性的要求正确性和对方数据重置的频率决定获取的周期。如有效性我们对数据的准确性要求不是100%的要求，且对方的对方数据变更工作频率也不是很高，则周期可设计得长一些，如每天一次，每几个小时一次等。对于如若是数据提供方的情况，则以对方的业务需要为准，但是对于标定获取数据的访问量大等特殊情况，应在需求量中或评审评判中做好说明和交代，以帮助开发设计

7、更满足需要的接口。选择合适的接口方式结合介面的不同类型和实时性要求类型两方面，可以选择合适的接口实现方式：a.mq 消息队列是一个中间件，数据提供服务方将数据放到中间件，数据解译获取方从中间件中获取数据。针对向多个系统同步基础数据的需要，消息队列是最适合的方式。若选择这种同步方式，要注意的一点是：增量同步还是全量同步，若是增量同步，对方是增量获取还是全量获取？若是全量同步，在什么情况下，对方应该及时更新数据，什么情况下应该及时更新数据？b.otter 同步数据同步方直接访问数据获取方的数据表将数据写入对应的表中，这些方式实时性最高，若对数据的准确性要求很高，此方式是很好的数据同步方式。c.ht

8、tp一般在功能设计中常用的接口是此种方式，双方通过http 地址保持数据同步和通信。在设计具体的数据同步接口时，具体的方式产品经理不用关注，由合作开发一般性根据需求设计合理的方式，然后产品可帮助开发一起确定所选方法是否满足业务需要。除非业务上有特殊要求，则在需求中可中会选定具体的方式。不同的介面使用场景，需要关注的点和交代清楚的规则不一样，以主动 / 被动 +数据使用方 / 数据获取方的维度，有以下四种情况：如果是向对方系统主动推送数据，则可按以下方式整理接口需求-鬼口名师句 3是靖岩遇XXX总招我罐二一段口用安，.他一下网口俱用的辱片事W村方鹿口的证词店址1就方/于r册西或一值堆号及功底*电

9、时普如耳机现字总理办吊回iFMKiijinJtJi* 效法词中妁寸层的各用力吐君密晕立舞上出餐学.V也修乳字巾若相7 H用,三招P _；事琮虫与夏根慨IT若0汾计家HMU蕈0L ：#A.田为修口实喳时工程痴，番帼里此埸连噎享国口幢+离真业第中字IR必一的亨汗力回耳网i.b方系小肃父早检的珞式看或U iK京外*证班加.西甲网原强91惇 讳一是用步的对苒不多搜凶ft品.去 退回循货.血里对的怪肝霍在岂打原 H 业军:,村在块壮能横履且同方句Mm n|f7B.御在R中餐不也粒壮 不町K空怪.劈加曾用即事件附阳 机-卦依=他掌息毡弼步矢限美KM蚪通琨沅羽的逅目虫.如果是对方主动来获取数据，则可按以下方

10、式整理接口 需求瑶口宅前TtaJS笠柱取XXX司罐的样口口建1.时方本鹿访问盘凄;JR业务用豪工一次胜*河壮志的无廿 （即华嘉.听BI3内右均定nsi里唯 江雄最一曳地嘱受艮明庄处医帆和写成名棘不做黑着亍州嬖H电研鹿语求善;5药归来JS水苦捌可工委1Hs，等手季匕的HM91JW 装酋梅t2R号版应语驳黑收法川星雪E出ST着足争冲酎忘词向府话情星珂X的青京譬实业抽中与盟的-倡方便灯方；骂没席个争触费或割的器就峦RE否域读求，R（题就提粕犹Sffi言左在”幅i据二位飞信鱼=科*覆，Itt 映HL表利MR”11 回WN.注铝直力定宜靶R用里盘MWftffiTE返回的小糟身/*申静不“要6“：给对方的

11、西塞羊四纲M逻塞一此屏分是爆d.因为曙口工运时工题费哼捌此落至正字厉空5.H案出借中下期加修例手E/帝苴*匹配书第riii啊.石口衽不利理逅同空情.如果是被动接收对方推送的数据，则可按以下方式整理 接口需求攫口名脸乏细或其数察的用口71 口搞理1浦KS牌布电/小药埠景2元耳限*伟/收审制附的费摩皿卡话*I!字性名称享用修述示楣，司在可斤71|1.减豆到的导比的名航工此蓦肉也见盛上帕当字, *判后的宁氐鸟花工喜序妁字域名陆出JF熊相嘉此事等设计宁R右宜将上猿意息离豹场中学嬲Hit例产1.对是当题审的要*?季刊界而后力了向证髀市一号瓜雷特FS仁曲MMN1不肺望性邕K叼町密环月青同的U谩品壮关；第源

12、幽1之或亘芸也冠国成曲的建阳1.如果主动从对方获取数据，则可按以下方式整理接口需 求Q之总HxxK 1-吃小米xxija更为桀n桂口碣速1退掌仇曲H前于用产兵切性呻打加打】丹值串JT*.品需看家式小瞿t辟口情什”布打时*,可亡检口9也打痛之心存地金由才计虢带一七曲号，段泞职土方助打外卓机飘3对方的博西向咏址字姓名题字才来尊示阴浏湾造证爱则国求事也1对方*旗忙城的修琼苫薜2此名禅是空里上的名字，IWwrrfKK工乐事靠妁孝俊名lurffjtMtt肚若*Kt汁janntizti.此闻珏品 吃.用内接口我改对二用 富雯糠衽比描述蛇宇用窜 事.其业低中窜收的友事阕子对百氏祝利此字冉的格式末.9 要果博构通现制，书不依叱规则收 it. 专利用方不备IM就疝.合 AMSH.实业需中字建的H例子名黄1方便忸副息即。堂撒狂期到的g露IE城中成切用舌冉状？值1.1存加长*, JM温总或加配不存在,Msana.我可夫N返囱*制里比?封方也Ui的看#W臣函回,敷的.应返回种共吸乘因.此 累通用子定阻状脚诵取失也的再因萩哂早出工苒早田荏业豪二的卡密门豕旭宜的前窗门检ttMH1#谪主应司.脚不可用呈2岁到裁第七为了