如何寫一份接口需求文檔？

在產品設計工作中，或多或少都會需要用到接口，特別是業務導向性的系統，接口幾乎是必不可少的功能。那么什么是接口？如何寫一份能準確表達業務需求的接口需求文檔呢？

一、什么是接口

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

要理解接口是什么，首先理解一下為什么要用接口？兩個獨立的系統，它們的數據或程序是獨立的，這就使得它們無法直接訪問對方的數據庫或程序（兩個獨立的數據相當于兩個獨立的家庭，每個家庭肯定是不允許外人隨便進入的，否則會發生偷竊等后果嚴重的事件）。但是某些業務場景下，獨立的系統之間又必須相互共享數據或共用一套程序邏輯，如統一業務流程上的不同業務操作系統，下游系統的業務依賴于上游系統的數據。

既然如此為什么不把它們設計成一個系統，這樣不就沒有上面的問題了嗎？這是因為有的業務流程很長很復雜，如果設計成一個系統，整個系統變得很龐雜，不論是功能設計、開發維護都很難。因此一般都會把雖然有上下游業務關系但又有清晰邊界的業務劃分成獨立的系統實現，如采購系統和倉儲系統。此外，很多時候我們需要獲取的數據是我們外部其他公司擁有的數據，更不可能設計成同一個系統了。

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

二、如何設計接口

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

a.若是主動訪問，有兩種情況，一是我方是數據的使用方，需要主動從對方獲取數據；二是我方是數據的提供方，需要主動將數據同步給對方。主動訪問時無需做接口，而是訪問對方的接口，要搞清楚的問題是：我們需要在什么節點訪問對方的接口？是用戶觸發某個操作的時候實時去訪問？還是沒有實時性要求，只是周期性地訪問？

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

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

若我方是數據的提供方且提供的數據是下游系統需要的實時要求高的數據則更多地用實時同步；若是基礎數據，則選擇周期性同步的方式。

b.若是被動請求，有兩種情況，一是我方是數據提供方，需要對方來獲取數據；二是我方是數據使用方，需要對方主動將數據同步過來。被動請求需要提供接口供對方訪問，此時要搞清楚：讓對方來訪問的時候，需要提供什么樣的參數？根據他提供的參數我們需要返回什么數據？這些數據從哪里取值？

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

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

2.搞清楚數據交互的實時性要求。

a.對于我方是數據使用方的情況，要根據業務的需要決定獲取數據的實時性。如上文所說，如果是用戶使用功能時需要的數據就是即時性訪問；如果是定期獲取基礎數據，根據我們對數據準確性的要求和對方數據變更的頻率決定獲取的周期，如我們對數據的準確性要求不是100%的要求，且對方的數據變更頻率也不是很高，則周期可設計的長一些，如每天一次，每幾個小時一次等。

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

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

結合接口的不同類型和實時性要求兩方面，可以選擇合適的接口實現方式：

a.mq消息隊列：是一個中間件，數據提供方將數據放到中間件，數據獲取方從中間件中獲取數據。針對向多個系統同步基礎數據的需要，消息隊列是最適合的方式。若選擇這種同步方式，要注意的一點是：增量同步還是全量同步，若是增量同步，對方是增量獲取還是全量獲取？若是全量同步，在什么情況下，對方應該更新數據，什么情況下應該更新數據？

b.otter同步：數據同步方直接訪問數據獲取方的數據表將數據寫入對應的表中，這種方式實時性最高，若對數據的準確性要求很高，此方式是很好的數據同步方式。

c.http：一般在功能設計中常用的接口是此種方式，雙方通過http地址保持數據同步和通信。

在設計具體的數據同步接口時，具體的方式產品經理不用關注，由開發根據需求設計合理的方式，然后產品可幫助開發一起確定所選方式是否滿足業務需要。除非業務上有特殊要求，則在需求中可指定具體的方式。

三、如何編寫接口文檔

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

1.如果是向對方系統主動推送數據，則可按以下方式整理接口需求：

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

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

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

數據復制服務 DRS 數據庫

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。