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

一、什么是接口

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

要理解接口是什么，首先理解一下為什么要用接口？

兩個獨立的系統(tǒng)，它們的數(shù)據(jù)或程序是獨立的，這就使得它們無法直接訪問對方的數(shù)據(jù)庫或程序（兩個獨立的數(shù)據(jù)相當(dāng)于兩個獨立的家庭，每個家庭肯定是不允許外人隨便進入的，否則會發(fā)生偷竊等后果嚴重的事件）。但是某些業(yè)務(wù)場景下，獨立的系統(tǒng)之間又必須相互共享數(shù)據(jù)或共用一套程序邏輯，如統(tǒng)一業(yè)務(wù)流程上的不同業(yè)務(wù)操作系統(tǒng)，下游系統(tǒng)的業(yè)務(wù)依賴于上游系統(tǒng)的數(shù)據(jù)。

既然如此為什么不把它們設(shè)計成一個系統(tǒng)，這樣不就沒有上面的問題了嗎？

這是因為有的業(yè)務(wù)流程很長很復(fù)雜，如果設(shè)計成一個系統(tǒng)，整個系統(tǒng)變得很龐雜，不論是功能設(shè)計、開發(fā)維護都很難。因此一般都會把雖然有上下游業(yè)務(wù)關(guān)系但又有清晰邊界的業(yè)務(wù)劃分成獨立的系統(tǒng)實現(xiàn)，如采購系統(tǒng)和倉儲系統(tǒng)。此外，很多時候我們需要獲取的數(shù)據(jù)是我們外部其他公司擁有的數(shù)據(jù)，更不可能設(shè)計成同一個系統(tǒng)了。

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

二、如何設(shè)計接口

1. 搞清楚是主動訪問還是被動請求：

a. 若是主動訪問，有兩種情況：

一是我方是數(shù)據(jù)的使用方，需要主動從對方獲取數(shù)據(jù)；二是我方是數(shù)據(jù)的提供方，需要主動將數(shù)據(jù)同步給對方。

主動訪問時無需做接口，而是訪問對方的接口，要搞清楚的問題是：我們需要在什么節(jié)點訪問對方的接口？是用戶觸發(fā)某個操作的時候?qū)崟r去訪問？還是沒有實時性要求，只是周期性地訪問？

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

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

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

b. 若是被動請求，有兩種情況：

一是我方是數(shù)據(jù)提供方，需要對方來獲取數(shù)據(jù)；二是我方是數(shù)據(jù)使用方，需要對方主動將數(shù)據(jù)同步過來。

被動請求需要提供接口供對方訪問，此時要搞清楚：讓對方來訪問的時候，需要提供什么樣的參數(shù)？根據(jù)他提供的參數(shù)我們需要返回什么數(shù)據(jù)？這些數(shù)據(jù)從哪里取值？

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

若我方是數(shù)據(jù)使用方且讓對方將數(shù)據(jù)主動同步過來，此種場景典型如——我們是業(yè)務(wù)的下游，上游系統(tǒng)產(chǎn)生數(shù)據(jù)后，需要將數(shù)據(jù)同步到下游系統(tǒng)讓流程繼續(xù)進行，并且流程的及時性要求高，不能有延遲。這種情況下，只有上游系統(tǒng)知道什么節(jié)點產(chǎn)生了數(shù)據(jù)，因此只有等他產(chǎn)生數(shù)據(jù)后主動推送給下游系統(tǒng)，因為下游系統(tǒng)因無法知道數(shù)據(jù)生成的時間，也就無法及時去獲取數(shù)據(jù)，這時最好的方式是讓對方主動將數(shù)據(jù)同步過來。

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

a. 對于我方是數(shù)據(jù)使用方的情況，要根據(jù)業(yè)務(wù)的需要決定獲取數(shù)據(jù)的實時性。

如上文所說，如果是用戶使用功能時需要的數(shù)據(jù)就是即時性訪問。如果是定期獲取基礎(chǔ)數(shù)據(jù)，根據(jù)我們對數(shù)據(jù)準確性的要求和對方數(shù)據(jù)變更的頻率決定獲取的周期。如我們對數(shù)據(jù)的準確性要求不是100%的要求，且對方的數(shù)據(jù)變更頻率也不是很高，則周期可設(shè)計得長一些，如每天一次，每幾個小時一次等。

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

3. 選擇合適的接口方式

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

a. mq消息隊列

是一個中間件，數(shù)據(jù)提供方將數(shù)據(jù)放到中間件，數(shù)據(jù)獲取方從中間件中獲取數(shù)據(jù)。針對向多個系統(tǒng)同步基礎(chǔ)數(shù)據(jù)的需要，消息隊列是最適合的方式。

若選擇這種同步方式，要注意的一點是：增量同步還是全量同步，若是增量同步，對方是增量獲取還是全量獲?。咳羰侨客?，在什么情況下，對方應(yīng)該更新數(shù)據(jù)，什么情況下應(yīng)該更新數(shù)據(jù)？

b. otter同步

數(shù)據(jù)同步方直接訪問數(shù)據(jù)獲取方的數(shù)據(jù)表將數(shù)據(jù)寫入對應(yīng)的表中，這種方式實時性最高，若對數(shù)據(jù)的準確性要求很高，此方式是很好的數(shù)據(jù)同步方式。

c. http

一般在功能設(shè)計中常用的接口是此種方式，雙方通過http地址保持數(shù)據(jù)同步和通信。

在設(shè)計具體的數(shù)據(jù)同步接口時，具體的方式產(chǎn)品經(jīng)理不用關(guān)注，由開發(fā)根據(jù)需求設(shè)計合理的方式，然后產(chǎn)品可幫助開發(fā)一起確定所選方式是否滿足業(yè)務(wù)需要。除非業(yè)務(wù)上有特殊要求，則在需求中可指定具體的方式。

三、如何編寫接口文檔

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

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

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

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

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

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

#專欄作家#

果果，人人都是產(chǎn)品經(jīng)理專欄作家。擅長業(yè)務(wù)導(dǎo)向性的產(chǎn)品設(shè)計，以及對業(yè)務(wù)流程的梳理和復(fù)雜問題的拆解，希望能找到產(chǎn)品工作的操作指南和方法論，不斷搭建自己的知識體系

本文原創(chuàng)發(fā)布于人人都是產(chǎn)品經(jīng)理。未經(jīng)許可，禁止轉(zhuǎn)載

題圖來自Unsplash, 基于CC0協(xié)議