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

一、什么是接口

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

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

兩個(gè)獨(dú)立的系統(tǒng)，它們的數(shù)據(jù)或程序是獨(dú)立的，這就使得它們無(wú)法直接訪問對(duì)方的數(shù)據(jù)庫(kù)或程序（兩個(gè)獨(dú)立的數(shù)據(jù)相當(dāng)于兩個(gè)獨(dú)立的家庭，每個(gè)家庭肯定是不允許外人隨便進(jìn)入的，否則會(huì)發(fā)生偷竊等后果嚴(yán)重的事件）。但是某些業(yè)務(wù)場(chǎng)景下，獨(dú)立的系統(tǒng)之間又必須相互共享數(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)，這樣不就沒有上面的問題了嗎？

這是因?yàn)橛械臉I(yè)務(wù)流程很長(zhǎng)很復(fù)雜，如果設(shè)計(jì)成一個(gè)系統(tǒng)，整個(gè)系統(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)了。

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

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

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

a. 若是主動(dòng)訪問，有兩種情況：

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

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

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

若我方是數(shù)據(jù)的使用方且需要的數(shù)據(jù)是一些跟用戶實(shí)時(shí)操作無(wú)關(guān)的基礎(chǔ)數(shù)據(jù)，如客服系統(tǒng)需要從其他業(yè)務(wù)系統(tǒng)獲取用戶的基礎(chǔ)數(shù)據(jù)，以在系統(tǒng)中的某些功能下展示用戶的信息（如客服在處理客訴等問題時(shí)，需要知道客戶的一些詳細(xì)信息，這些信息只有業(yè)務(wù)系統(tǒng)有）。這種情況下，一般會(huì)新增一個(gè)腳本定時(shí)（如兩小時(shí)一次）訪問對(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ù)，則選擇周期性同步的方式。

b. 若是被動(dòng)請(qǐng)求，有兩種情況：

一是我方是數(shù)據(jù)提供方，需要對(duì)方來(lái)獲取數(shù)據(jù)；二是我方是數(shù)據(jù)使用方，需要對(duì)方主動(dòng)將數(shù)據(jù)同步過(guò)來(lái)。

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

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

若我方是數(shù)據(jù)使用方且讓對(duì)方將數(shù)據(jù)主動(dòng)同步過(guò)來(lái)，此種場(chǎ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)因無(wú)法知道數(shù)據(jù)生成的時(shí)間，也就無(wú)法及時(shí)去獲取數(shù)據(jù)，這時(shí)最好的方式是讓對(duì)方主動(dòng)將數(shù)據(jù)同步過(guò)來(lái)。

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

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

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

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

3. 選擇合適的接口方式

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

a. mq消息隊(duì)列

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

若選擇這種同步方式，要注意的一點(diǎn)是：增量同步還是全量同步，若是增量同步，對(duì)方是增量獲取還是全量獲??？若是全量同步，在什么情況下，對(duì)方應(yīng)該更新數(shù)據(jù)，什么情況下應(yīng)該更新數(shù)據(jù)？

b. otter同步

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

c. http

一般在功能設(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ù)上有特殊要求，則在需求中可指定具體的方式。

三、如何編寫接口文檔

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

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

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

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

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

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

#專欄作家#

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

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

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