4個(gè)要點(diǎn),編寫一份接口需求文檔

1、4 個(gè)要點(diǎn)，編寫一份接口需求文檔在產(chǎn)品設(shè)計(jì)工作中，或多或少都會(huì)需要用到接口，特別是業(yè)務(wù)導(dǎo)向性的系統(tǒng)，接口幾乎是必不可少的功能。那么什么是接口？如何寫一份能準(zhǔn)確表達(dá)業(yè)務(wù)需求的接口需求呢？百科上為對(duì)接口的定義： API（ ApplicationProgrammingInterface, 應(yīng)用程序編程接口）是一些預(yù) 先定義的函數(shù)，目的是提供應(yīng)用程序與開發(fā)人員某軟件或硬件得以訪問(wèn)一組例程的能力，而又無(wú)需訪問(wèn)源碼，或理解最高層工作技術(shù)細(xì)節(jié)機(jī)制的細(xì)節(jié)。要理解接口是什么，首先理解一下為什么要用接口？?jī)蓚€(gè)獨(dú)立的系統(tǒng)，它們的數(shù)據(jù)或程序是獨(dú)立的，這就使得它們無(wú)法直接訪問(wèn)對(duì)方的數(shù)據(jù)庫(kù)或程序（兩個(gè)獨(dú)立數(shù)據(jù)庫(kù)相當(dāng)于兩個(gè)

2、獨(dú)立的家庭，每個(gè)家庭肯定是不允許外人隨便進(jìn)入的，否則會(huì)發(fā)生偷竊等后果嚴(yán)重的事件）。但是某些業(yè)務(wù)場(chǎng)景下，獨(dú)立的系統(tǒng)之間又必須相互關(guān)系相互共享數(shù)據(jù)或共用一套程序邏輯，如統(tǒng)一業(yè)務(wù)流程上的不同業(yè)務(wù)操作系統(tǒng)，下游系統(tǒng)的業(yè)務(wù)依賴于上游系統(tǒng)的數(shù)據(jù)。既然如此為什么不把它們?cè)O(shè)計(jì)成一個(gè)系統(tǒng)，這樣不就沒有上面不是的問(wèn)題了嗎？這是因?yàn)橛械臉I(yè)務(wù)流程很長(zhǎng)很復(fù)雜，如果設(shè)計(jì)成一個(gè)系統(tǒng)內(nèi)，整個(gè)網(wǎng)絡(luò)系統(tǒng)變得很龐雜，不論是功能設(shè)計(jì)、開發(fā)維護(hù)都很難。因此一般都會(huì)把雖然有上下游業(yè)務(wù)關(guān)系但又有清晰邊界的業(yè)務(wù)劃分成獨(dú)立的系統(tǒng)實(shí)現(xiàn)，如采購(gòu)系統(tǒng)和倉(cāng)儲(chǔ)系統(tǒng)。此外，很多時(shí)候我們需要獲取的數(shù)據(jù)是我們外部其他公司擁有的數(shù)據(jù)，更為不可能設(shè)計(jì)成同一個(gè)系統(tǒng)

3、了。基于以上兩點(diǎn)：接口就是兩個(gè)獨(dú)立系統(tǒng)之間電腦系統(tǒng)同步數(shù)據(jù)或訪問(wèn)對(duì)方程序的途徑。搞清楚是主動(dòng)訪問(wèn)還是被動(dòng)請(qǐng)求：若是主動(dòng)訪問(wèn)，有兩種情況：一是我方是數(shù)據(jù)的用到方，需要有主動(dòng)從對(duì)方獲取數(shù)據(jù)；二是我方是數(shù)據(jù)的獲取方，需要主動(dòng)將數(shù)據(jù)同步給對(duì)方。主動(dòng)訪問(wèn)之前無(wú)需做接口，而是訪問(wèn)對(duì)方的接口，要搞清楚的問(wèn)題是：我們需要在什么節(jié)點(diǎn)訪問(wèn)對(duì)方的接口？是用戶觸發(fā)某個(gè)操作的時(shí)候?qū)崟r(shí)去訪問(wèn)？還是沒有實(shí)時(shí)性要求，只是周期性地訪問(wèn)？若我方是數(shù)據(jù)的使用方且能夠的數(shù)據(jù)是用戶使用某個(gè)功能必須的數(shù)據(jù)，因此必須在用戶操作時(shí)實(shí)時(shí)去訪問(wèn)對(duì)方的接口獲取數(shù)據(jù)并展示給用戶，典型的有我們注冊(cè)某網(wǎng)站申領(lǐng)時(shí)獲取驗(yàn)證碼的功能。若我方是數(shù)據(jù)的使用方且是

4、的數(shù)據(jù)需要一些跟用戶實(shí)時(shí)操作無(wú)關(guān)的基礎(chǔ)數(shù)據(jù)，如客服系統(tǒng)需要從其他業(yè)務(wù)系統(tǒng)獲取用戶的基礎(chǔ)，以在系統(tǒng)的某些功能下展示用戶的信息（如客服在處理接線員客訴等問(wèn)題時(shí)，可能需要知道客戶的一些表中詳細(xì)信息，這些信息只有業(yè)務(wù)子系統(tǒng)有）。這種情況下，一般會(huì)新增一個(gè)腳本定時(shí)（如兩小時(shí)一次）訪問(wèn)對(duì)方的接口將數(shù)據(jù)獲取過(guò)來(lái)存儲(chǔ)到自己的數(shù)據(jù)庫(kù)，在用到的時(shí)候直接從自己數(shù)據(jù)庫(kù)獲取并展示。若我方是數(shù)據(jù)的提供方且提供的數(shù)據(jù)是下游系統(tǒng)需要有實(shí)時(shí)要求高的數(shù)據(jù)則更多地用實(shí)時(shí)同步；若是基礎(chǔ)數(shù)據(jù)，則選擇周期性同步的這種方式。若是被動(dòng)請(qǐng)求，有兩種情況：一是我方是數(shù)據(jù)直接提供方，需要對(duì)方來(lái)獲取數(shù)據(jù)；二是我方是數(shù)據(jù)重復(fù)使用方，需要對(duì)方主動(dòng)將數(shù)據(jù)

5、同步過(guò)來(lái)。被動(dòng)請(qǐng)求需要提供接口供對(duì)方訪問(wèn)，此時(shí)要搞清楚：讓假裝來(lái)訪問(wèn)的時(shí)候，需要提供什么樣的參數(shù)？根據(jù)他直接提供的離開參數(shù)我們需要返回什么數(shù)據(jù)？這些數(shù)據(jù)從哪里取值？若有一些數(shù)據(jù)的來(lái)源是本系統(tǒng)，其他系統(tǒng)需要使用這些數(shù)據(jù)，則 可提供接口讓其他系統(tǒng)通過(guò)訪問(wèn)接口獲取這些數(shù)據(jù)。若我方是數(shù)據(jù)使用方且讓對(duì)方連動(dòng)將數(shù)據(jù)主動(dòng)同步過(guò)來(lái)，此種場(chǎng)景典型如我們是業(yè)務(wù)的下游，上游系統(tǒng)內(nèi)產(chǎn)生數(shù)據(jù)后，可能需要 將數(shù)據(jù)同步到下游系統(tǒng)讓流程繼續(xù)進(jìn)行，并且流程的及時(shí)性要求非常 高，不能有延遲。這種情況下，只有系統(tǒng)知道什么節(jié)點(diǎn)產(chǎn)生了數(shù)據(jù)， 因此只有等他產(chǎn)生數(shù)據(jù)而后主動(dòng)推送給下游系統(tǒng)，因?yàn)橄掠我驘o(wú)法知 道數(shù)據(jù)生成的時(shí)間，也就無(wú)法及時(shí)去

6、獲取數(shù)據(jù)，這時(shí)最好的方式是讓 對(duì)方主動(dòng)將其要求數(shù)據(jù)同步過(guò)來(lái)。搞清楚數(shù)據(jù)交互的實(shí)時(shí)性要求對(duì)于我方我方是數(shù)字使用方的情況，要根據(jù)業(yè)務(wù)的需要決定獲取數(shù)據(jù)的實(shí)時(shí)性。如上文所說(shuō)，如果是用戶使用功能時(shí)需要的數(shù)據(jù)功用就是即時(shí)性訪問(wèn)。如果是定期獲取基礎(chǔ)數(shù)據(jù)，根據(jù)我們對(duì)數(shù)據(jù)準(zhǔn)確性的要求正確性和對(duì)方數(shù)據(jù)重置的頻率決定獲取的周期。如有效性我們對(duì)數(shù)據(jù)的準(zhǔn)確性要求不是100%的要求，且對(duì)方的對(duì)方數(shù)據(jù)變更工作頻率也不是很高，則周期可設(shè)計(jì)得長(zhǎng)一些，如每天一次，每幾個(gè)小時(shí)一次等。對(duì)于如若是數(shù)據(jù)提供方的情況，則以對(duì)方的業(yè)務(wù)需要為準(zhǔn)，但是對(duì)于標(biāo)定獲取數(shù)據(jù)的訪問(wèn)量大等特殊情況，應(yīng)在需求量中或評(píng)審評(píng)判中做好說(shuō)明和交代，以幫助開發(fā)設(shè)計(jì)

7、更滿足需要的接口。選擇合適的接口方式結(jié)合介面的不同類型和實(shí)時(shí)性要求類型兩方面，可以選擇合適的接口實(shí)現(xiàn)方式：a.mq 消息隊(duì)列是一個(gè)中間件，數(shù)據(jù)提供服務(wù)方將數(shù)據(jù)放到中間件，數(shù)據(jù)解譯獲取方從中間件中獲取數(shù)據(jù)。針對(duì)向多個(gè)系統(tǒng)同步基礎(chǔ)數(shù)據(jù)的需要，消息隊(duì)列是最適合的方式。若選擇這種同步方式，要注意的一點(diǎn)是：增量同步還是全量同步，若是增量同步，對(duì)方是增量獲取還是全量獲??？若是全量同步，在什么情況下，對(duì)方應(yīng)該及時(shí)更新數(shù)據(jù)，什么情況下應(yīng)該及時(shí)更新數(shù)據(jù)？b.otter 同步數(shù)據(jù)同步方直接訪問(wèn)數(shù)據(jù)獲取方的數(shù)據(jù)表將數(shù)據(jù)寫入對(duì)應(yīng)的表中，這些方式實(shí)時(shí)性最高，若對(duì)數(shù)據(jù)的準(zhǔn)確性要求很高，此方式是很好的數(shù)據(jù)同步方式。c.ht

8、tp一般在功能設(shè)計(jì)中常用的接口是此種方式，雙方通過(guò)http 地址保持?jǐn)?shù)據(jù)同步和通信。在設(shè)計(jì)具體的數(shù)據(jù)同步接口時(shí)，具體的方式產(chǎn)品經(jīng)理不用關(guān)注，由合作開發(fā)一般性根據(jù)需求設(shè)計(jì)合理的方式，然后產(chǎn)品可幫助開發(fā)一起確定所選方法是否滿足業(yè)務(wù)需要。除非業(yè)務(wù)上有特殊要求，則在需求中可中會(huì)選定具體的方式。不同的介面使用場(chǎng)景，需要關(guān)注的點(diǎn)和交代清楚的規(guī)則不一樣，以主動(dòng) / 被動(dòng) +數(shù)據(jù)使用方 / 數(shù)據(jù)獲取方的維度，有以下四種情況：如果是向?qū)Ψ较到y(tǒng)主動(dòng)推送數(shù)據(jù)，則可按以下方式整理接口需求-鬼口名師句 3是靖巖遇XXX總招我罐二一段口用安，.他一下網(wǎng)口俱用的辱片事W村方鹿口的證詞店址1就方/于r冊(cè)西或一值堆號(hào)及功底*電

9、時(shí)普如耳機(jī)現(xiàn)字總理辦吊回iFMKiijinJtJi* 效法詞中妁寸層的各用力吐君密暈立舞上出餐學(xué).V也修乳字巾若相7 H用,三招P _；事琮蟲與夏根慨IT若0汾計(jì)家HMU蕈0L ：#A.田為修口實(shí)喳時(shí)工程癡，番幗里此埸連噎享國(guó)口幢+離真業(yè)第中字IR必一的亨汗力回耳網(wǎng)i.b方系小肅父早檢的珞式看或U iK京外*證班加.西甲網(wǎng)原強(qiáng)91惇 諱一是用步的對(duì)苒不多搜兇ft品.去 退回循貨.血里對(duì)的怪肝霍在豈打原 H 業(yè)軍:,村在塊壯能橫履且同方句Mm n|f7B.御在R中餐不也粒壯 不町K空怪.劈加曾用即事件附陽(yáng) 機(jī)-卦依=他掌息氈弼步矢限美KM蚪通琨沅羽的逅目蟲.如果是對(duì)方主動(dòng)來(lái)獲取數(shù)據(jù)，則可按以下方

10、式整理接口 需求瑤口宅前TtaJS笠柱取XXX司罐的樣口口建1.時(shí)方本鹿訪問(wèn)盤凄;JR業(yè)務(wù)用豪工一次勝*河壯志的無(wú)廿 （即華嘉.聽BI3內(nèi)右均定nsi里唯 江雄最一曳地囑受艮明莊處醫(yī)帆和寫成名棘不做黑著亍州嬖H電研鹿語(yǔ)求善;5藥歸來(lái)JS水苦捌可工委1Hs，等手季匕的HM91JW 裝酋梅t2R號(hào)版應(yīng)語(yǔ)駁黑收法川星雪E出ST著足爭(zhēng)沖酎忘詞向府話情星珂X的青京譬實(shí)業(yè)抽中與盟的-倡方便燈方；罵沒席個(gè)爭(zhēng)觸費(fèi)或割的器就巒RE否域讀求，R（題就提粕猶Sffi言左在”幅i據(jù)二位飛信魚=科*覆，Itt 映HL表利MR”11 回WN.注鋁直力定宜靶R用里盤MWftffiTE返回的小糟身/*申靜不“要6“：給對(duì)方的

11、西塞羊四綱M邏塞一此屏分是爆d.因?yàn)槭锟诠み\(yùn)時(shí)工題費(fèi)哼捌此落至正字厲空5.H案出借中下期加修例手E/帝苴*匹配書第riii啊.石口衽不利理逅同空情.如果是被動(dòng)接收對(duì)方推送的數(shù)據(jù)，則可按以下方式整理 接口需求攫口名臉?lè)?xì)或其數(shù)察的用口71 口搞理1浦KS牌布電/小藥埠景2元耳限*偉/收審制附的費(fèi)摩皿卡話*I!字性名稱享用修述示楣，司在可斤71|1.減豆到的導(dǎo)比的名航工此驀肉也見盛上帕當(dāng)字, *判后的寧氐鳥花工喜序妁字域名陸出JF熊相嘉此事等設(shè)計(jì)寧R右宜將上猿意息離豹場(chǎng)中學(xué)嬲Hit例產(chǎn)1.對(duì)是當(dāng)題審的要*?季刊界而后力了向證髀市一號(hào)瓜雷特FS仁曲MMN1不肺望性邕K叼町密環(huán)月青同的U謾品壯關(guān)；第源

12、幽1之或亙蕓也冠國(guó)成曲的建陽(yáng)1.如果主動(dòng)從對(duì)方獲取數(shù)據(jù)，則可按以下方式整理接口需 求Q之總HxxK 1-吃小米xxija更為桀n桂口碣速1退掌仇曲H前于用產(chǎn)兵切性呻打加打】丹值串JT*.品需看家式小瞿t辟口情什”布打時(shí)*,可亡檢口9也打痛之心存地金由才計(jì)虢帶一七曲號(hào)，段濘職土方助打外卓機(jī)飄3對(duì)方的博西向詠址字姓名題字才來(lái)尊示陰瀏灣造證愛則國(guó)求事也1對(duì)方*旗忙城的修瓊苫薜2此名禪是空里上的名字，IWwrrfKK工樂(lè)事靠妁孝俊名lurffjtMtt肚若*Kt汁janntizti.此聞玨品 吃.用內(nèi)接口我改對(duì)二用 富雯糠衽比描述蛇宇用竄 事.其業(yè)低中竄收的友事闋子對(duì)百氏祝利此字冉的格式末.9 要果博構(gòu)通現(xiàn)制，書不依叱規(guī)則收 it. 專利用方不備IM就疝.合 AMSH.實(shí)業(yè)需中字建的H例子名黃1方便忸副息即。堂撒狂期到的g露IE城中成切用舌冉狀？值1.1存加長(zhǎng)*, JM溫總或加配不存在,Msana.我可夫N返囪*制里比?封方也Ui的看#W臣函回,敷的.應(yīng)返回種共吸乘因.此 累通用子定阻狀腳誦取失也的再因萩哂早出工苒早田荏業(yè)豪二的卡密門豕旭宜的前窗門檢ttMH1#謫主應(yīng)司.腳不可用呈2歲到裁第七為了