在產(chǎn)品設(shè)計(jì)工作中，或多或少都會需要用到接口咨堤，特別是業(yè)務(wù)導(dǎo)向性的系統(tǒng)菇篡，接口幾乎是必不可少的功能。那么什么是接口一喘？如何寫一份能準(zhǔn)確表達(dá)業(yè)務(wù)需求的接口需求文檔呢驱还？

一、什么是接口

百科上對接口的定義:API（Application Programming Interface,應(yīng)用程序編程接口）是一些預(yù)先定義的函數(shù)凸克，目的是提供應(yīng)用程序與開發(fā)人員基于某軟件或硬件得以訪問一組例程的能力议蟆，而又無需訪問源碼，或理解內(nèi)部工作機(jī)制的細(xì)節(jié)萎战。

要理解接口是什么咐容，首先理解一下為什么要用接口？兩個(gè)獨(dú)立的系統(tǒng)蚂维，它們的數(shù)據(jù)或程序是獨(dú)立的戳粒，這就使得它們無法直接訪問對方的數(shù)據(jù)庫或程序（兩個(gè)獨(dú)立的數(shù)據(jù)相當(dāng)于兩個(gè)獨(dú)立的家庭，每個(gè)家庭肯定是不允許外人隨便進(jìn)入的鸟雏，否則會發(fā)生偷竊等后果嚴(yán)重的事件）享郊。但是某些業(yè)務(wù)場景下，獨(dú)立的系統(tǒng)之間又必須相互共享數(shù)據(jù)或共用一套程序邏輯孝鹊，如統(tǒng)一業(yè)務(wù)流程上的不同業(yè)務(wù)操作系統(tǒng)炊琉，下游系統(tǒng)的業(yè)務(wù)依賴于上游系統(tǒng)的數(shù)據(jù)。

既然如此為什么不把它們設(shè)計(jì)成一個(gè)系統(tǒng)又活，這樣不就沒有上面的問題了嗎苔咪？這是因?yàn)橛械臉I(yè)務(wù)流程很長很復(fù)雜，如果設(shè)計(jì)成一個(gè)系統(tǒng)柳骄，整個(gè)系統(tǒng)變得很龐雜团赏，不論是功能設(shè)計(jì)、開發(fā)維護(hù)都很難耐薯。因此一般都會把雖然有上下游業(yè)務(wù)關(guān)系但又有清晰邊界的業(yè)務(wù)劃分成獨(dú)立的系統(tǒng)實(shí)現(xiàn)舔清，如采購系統(tǒng)和倉儲系統(tǒng)丝里。此外，很多時(shí)候我們需要獲取的數(shù)據(jù)是我們外部其他公司擁有的數(shù)據(jù)体谒，更不可能設(shè)計(jì)成同一個(gè)系統(tǒng)了杯聚。

基于以上兩點(diǎn)：接口就是兩個(gè)獨(dú)立系統(tǒng)之間同步數(shù)據(jù)或訪問對方程序的途徑。

二抒痒、如何設(shè)計(jì)接口

1.搞清楚是主動(dòng)訪問還是被動(dòng)請求：

a.若是主動(dòng)訪問幌绍，有兩種情況，一是我方是數(shù)據(jù)的使用方故响，需要主動(dòng)從對方獲取數(shù)據(jù)傀广；二是我方是數(shù)據(jù)的提供方，需要主動(dòng)將數(shù)據(jù)同步給對方彩届。主動(dòng)訪問時(shí)無需做接口伪冰，而是訪問對方的接口，要搞清楚的問題是：我們需要在什么節(jié)點(diǎn)訪問對方的接口惨缆？是用戶觸發(fā)某個(gè)操作的時(shí)候?qū)崟r(shí)去訪問糜值？還是沒有實(shí)時(shí)性要求，只是周期性地訪問坯墨？

若我方是數(shù)據(jù)的使用方且需要的數(shù)據(jù)是用戶使用某個(gè)功能必須的數(shù)據(jù)，因此必須在用戶操作時(shí)實(shí)時(shí)去訪問對方的接口獲取數(shù)據(jù)并展示給用戶病往，典型的有我們注冊某網(wǎng)站時(shí)獲取驗(yàn)證碼的功能捣染。

若我方是數(shù)據(jù)的使用方且需要的數(shù)據(jù)是一些跟用戶實(shí)時(shí)操作無關(guān)的基礎(chǔ)數(shù)據(jù)，如客服系統(tǒng)需要從其他業(yè)務(wù)系統(tǒng)獲取用戶的基礎(chǔ)數(shù)據(jù)停巷，以在系統(tǒng)中的某些功能下展示用戶的信息（如客服在處理客訴等問題時(shí)耍攘，需要知道客戶的一些詳細(xì)信息，這些信息只有業(yè)務(wù)系統(tǒng)有）畔勤，這種情況蕾各，一般會新增一個(gè)腳本定時(shí)（如兩小時(shí)一次）訪問對方的接口將數(shù)據(jù)獲取過來存儲到自己的數(shù)據(jù)庫，在用到的時(shí)候直接從自己數(shù)據(jù)庫獲取并展示庆揪。

若我方是數(shù)據(jù)的提供方且提供的數(shù)據(jù)是下游系統(tǒng)需要的實(shí)時(shí)要求高的數(shù)據(jù)則更多地用實(shí)時(shí)同步式曲；若是基礎(chǔ)數(shù)據(jù)，則選擇周期性同步的方式缸榛。

b.若是被動(dòng)請求吝羞，有兩種情況，一是我方是數(shù)據(jù)提供方内颗，需要對方來獲取數(shù)據(jù)钧排；二是我方是數(shù)據(jù)使用方，需要對方主動(dòng)將數(shù)據(jù)同步過來均澳。被動(dòng)請求需要提供接口供對方訪問恨溜，此時(shí)要搞清楚：讓對方來訪問的時(shí)候符衔，需要提供什么樣的參數(shù)？根據(jù)他提供的參數(shù)我們需要返回什么數(shù)據(jù)糟袁？這些數(shù)據(jù)從哪里取值判族？

若有一些數(shù)據(jù)的來源是本系統(tǒng)，其他系統(tǒng)需要使用這些數(shù)據(jù)系吭，則可提供接口讓其他系統(tǒng)通過訪問接口獲取這些數(shù)據(jù)五嫂。

若我方是數(shù)據(jù)使用方且讓對方將數(shù)據(jù)主動(dòng)同步過來，此種場景典型的如我們是業(yè)務(wù)的下游肯尺，上游系統(tǒng)產(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)橄掠蜗到y(tǒng)因無法知道數(shù)據(jù)生成的時(shí)間，也就無法及時(shí)去獲取數(shù)據(jù)敬扛，這時(shí)最好的方式是讓對方主動(dòng)將數(shù)據(jù)同步過來晰洒。

2.搞清楚數(shù)據(jù)交互的實(shí)時(shí)性要求。

a.對于我方是數(shù)據(jù)使用方的情況啥箭，要根據(jù)業(yè)務(wù)的需要決定獲取數(shù)據(jù)的實(shí)時(shí)性谍珊。如上文所說，如果是用戶使用功能時(shí)需要的數(shù)據(jù)就是即時(shí)性訪問急侥；如果是定期獲取基礎(chǔ)數(shù)據(jù)砌滞，根據(jù)我們對數(shù)據(jù)準(zhǔn)確性的要求和對方數(shù)據(jù)變更的頻率決定獲取的周期，如我們對數(shù)據(jù)的準(zhǔn)確性要求不是100%的要求坏怪，且對方的數(shù)據(jù)變更頻率也不是很高贝润，則周期可設(shè)計(jì)的長一些，如每天一次铝宵，每幾個(gè)小時(shí)一次等打掘。

b.對于我方是數(shù)據(jù)提供方的情況，則以對方的業(yè)務(wù)需要為準(zhǔn)捉超，但是對于獲取數(shù)據(jù)的訪問量大等特殊情況胧卤，應(yīng)在需求中或評審中做好說明和交代，以幫助開發(fā)設(shè)計(jì)更滿足需要的接口拼岳。

3.選擇合適的接口方式枝誊。

結(jié)合接口的不同類型和實(shí)時(shí)性要求兩方面，可以選擇合適的接口實(shí)現(xiàn)方式：

a.mq消息隊(duì)列：是一個(gè)中間件惜纸，數(shù)據(jù)提供方將數(shù)據(jù)放到中間件叶撒，數(shù)據(jù)獲取方從中間件中獲取數(shù)據(jù)绝骚。針對向多個(gè)系統(tǒng)同步基礎(chǔ)數(shù)據(jù)的需要，消息隊(duì)列是最適合的方式祠够。若選擇這種同步方式压汪，要注意的一點(diǎn)是：增量同步還是全量同步，若是增量同步古瓤，對方是增量獲取還是全量獲戎蛊省？若是全量同步落君，在什么情況下穿香，對方應(yīng)該更新數(shù)據(jù)，什么情況下應(yīng)該更新數(shù)據(jù)绎速？

b.otter同步：數(shù)據(jù)同步方直接訪問數(shù)據(jù)獲取方的數(shù)據(jù)表將數(shù)據(jù)寫入對應(yīng)的表中皮获，這種方式實(shí)時(shí)性最高，若對數(shù)據(jù)的準(zhǔn)確性要求很高纹冤，此方式是很好的數(shù)據(jù)同步方式洒宝。

c.http：一般在功能設(shè)計(jì)中常用的接口是此種方式，雙方通過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ù)上有特殊要求，則在需求中可指定具體的方式橡庞。

三、如何編寫接口文檔

不同的接口使用場景印蔗，需要關(guān)注的點(diǎn)和交代清楚的規(guī)則不一樣扒最，以主動(dòng)/被動(dòng)+數(shù)據(jù)使用方/數(shù)據(jù)獲取方的維度，有以下四種情況：

1.如果是向?qū)Ψ较到y(tǒng)主動(dòng)推送數(shù)據(jù)吧趣，則可按以下方式整理接口需求：

2.如果是對方主動(dòng)來獲取數(shù)據(jù)，則可按以下方式整理接口需求：?

3.如果是被動(dòng)接收對方推送的數(shù)據(jù)耙厚，則可按以下方式整理接口需求：

4.如果主動(dòng)從對方獲取數(shù)據(jù)强挫，則可按以下方式整理接口需求：

PS:在下一篇文章中將以具體的文檔實(shí)例來說明不同的場景應(yīng)該考慮和注意的點(diǎn)。書寫過程中一些偏技術(shù)的點(diǎn)應(yīng)及時(shí)與開發(fā)咨詢和溝通薛躬，防止編寫的文檔與實(shí)際出入太大俯渤；接口的開發(fā)肯定涉及兩個(gè)系統(tǒng)，因此在評審前與對方產(chǎn)品對好文檔是必須的型宝，要保證雙方開發(fā)拿到的文檔標(biāo)準(zhǔn)是一樣的八匠，否則在開發(fā)過程中會出現(xiàn)雙方約定不一致導(dǎo)致需要修改的情況絮爷。