編輯導(dǎo)語(yǔ)：作為一名產(chǎn)品經(jīng)理，乍一看，接口需求似乎與產(chǎn)品經(jīng)理毫無(wú)關(guān)系，為什么要會(huì)？但其實(shí)產(chǎn)品經(jīng)理日常工作需要與其他部門(mén)溝通，當(dāng)業(yè)務(wù)繁雜時(shí)，了解接口需求有助于提高溝通的效率，為后續(xù)工作助力。本文分析了產(chǎn)品經(jīng)理需要掌握接口需求的原因及其如何寫(xiě)接口需求，一起來(lái)看看。

一、為什么產(chǎn)品經(jīng)理要寫(xiě)接口需求？

我目前就職的公司，整個(gè)集團(tuán)的產(chǎn)、研人員多大上千人，業(yè)務(wù)龐大且復(fù)雜。在這樣的環(huán)境，當(dāng)某個(gè)需求涉及到與其他業(yè)務(wù)線有數(shù)據(jù)上的交互時(shí)，需要產(chǎn)品經(jīng)理經(jīng)理去調(diào)研需求、并輸出接口需求文檔。

這樣的事情，對(duì)于像我這樣的公司老人來(lái)講，是非?？梢岳斫獾?。但是新加入公司或團(tuán)隊(duì)的產(chǎn)品，經(jīng)常會(huì)發(fā)出一個(gè)疑問(wèn)“為什么產(chǎn)品經(jīng)理需要寫(xiě)接口需求文檔”？

在小團(tuán)隊(duì)中，業(yè)務(wù)劃分不清晰，所有業(yè)務(wù)共用一個(gè)產(chǎn)、研團(tuán)隊(duì)，產(chǎn)品、開(kāi)發(fā)對(duì)全局的業(yè)務(wù)和業(yè)務(wù)涉及的數(shù)據(jù)流會(huì)比較熟悉。

在這種環(huán)境下，假設(shè)某個(gè)需求的方案，在實(shí)現(xiàn)過(guò)程中需要基于本業(yè)務(wù)系統(tǒng)和其他業(yè)務(wù)系統(tǒng)的數(shù)據(jù)來(lái)實(shí)現(xiàn)，就不需要產(chǎn)品經(jīng)理去寫(xiě)接口需求，開(kāi)發(fā)可基于對(duì)需求的理解，自行完成接口的需求梳理和接口的實(shí)現(xiàn)。

在大團(tuán)隊(duì)中，首先在組織架構(gòu)上會(huì)根據(jù)不同的業(yè)務(wù)線，劃分不同的業(yè)務(wù)部門(mén)和不同的產(chǎn)研團(tuán)隊(duì)，在這樣的組織中，每個(gè)業(yè)務(wù)線的開(kāi)發(fā)一般情況下只負(fù)責(zé)業(yè)務(wù)范圍內(nèi)的需求，不會(huì)交叉負(fù)責(zé)其他業(yè)務(wù)線的需求，從而就會(huì)造成不熟悉其他業(yè)務(wù)線的業(yè)務(wù)與數(shù)據(jù)流的現(xiàn)象。

在這種環(huán)境下，如某個(gè)需求的方案，在實(shí)現(xiàn)過(guò)程中需要基于本業(yè)務(wù)系統(tǒng)和其他業(yè)務(wù)系統(tǒng)的數(shù)據(jù)來(lái)實(shí)現(xiàn)，就需要產(chǎn)品經(jīng)理去調(diào)研并輸出接口需求。

舉個(gè)例子：營(yíng)銷團(tuán)隊(duì)的某個(gè)營(yíng)銷活動(dòng)，需要基于用戶的某些信息去判斷用戶是否可以參與活動(dòng)時(shí)，就需要營(yíng)銷團(tuán)隊(duì)產(chǎn)品經(jīng)理去了解用戶業(yè)務(wù)的業(yè)務(wù)、數(shù)據(jù)、如何獲取，并向開(kāi)發(fā)提出接口需求并提供接口需求說(shuō)明。

據(jù)我所了解的情況，很多業(yè)務(wù)龐大且復(fù)雜的公司，產(chǎn)品經(jīng)理在處理需求的過(guò)程中都有可能需要寫(xiě)接口需求：例如：順豐、金蝶、平安等等。

二、接口的自我介紹

大家好，我是你們已經(jīng)認(rèn)識(shí)很久的好朋友，我的名字叫“接口”。在平時(shí)的工作中，你們經(jīng)常會(huì)討論到我，并讓我?guī)湍憬鉀Q很多問(wèn)題。例如，前端的小姐姐需要查看用戶“小明”的姓名、性別、身高、地址等用戶信息時(shí)，她會(huì)將要求先告訴我，然后我會(huì)將前端小姐姐的要求轉(zhuǎn)達(dá)給后端的小哥哥，待后端小哥哥按要求完成任務(wù)之后，我就會(huì)將前端姐姐想要的信息告訴她。

• 任務(wù)名稱：用戶信息查詢
• 入?yún)ⅲú樵儣l件）：用戶姓名
• 出參（查詢結(jié)果）：用戶姓名、性別、身高、學(xué)歷、地址、聯(lián)系方式

以上是“我”的自我介紹。是的，我就是這么牛逼PLUS。但是，我只能同時(shí)幫你們完成一件事情。當(dāng)你們?cè)谕瓿蓴?shù)據(jù)寫(xiě)入的同時(shí)，需要刷新頁(yè)面查詢最新的數(shù)據(jù)時(shí)，我可以與我的兄弟姐妹聯(lián)手滿足你們的需求。

無(wú)論是在前端小姐姐與后端小哥哥之間，或是，在訂單大哥與倉(cāng)儲(chǔ)大哥之間，我都可以利用我的能力幫你們解決很多問(wèn)題，且你們只需要告訴我入?yún)ⅰ⒊鰠?、以及其他要求（例如：并發(fā)量、調(diào)用量、是否批量等）。下圖是某公司官網(wǎng)開(kāi)放平臺(tái)的一個(gè)接口案例。

三、怎么寫(xiě)接口需求

在我之前的發(fā)布的內(nèi)容《需求文檔遺漏問(wèn)題的良方：認(rèn)識(shí)它并干掉它》當(dāng)中，有提到過(guò)，僅從功能的角度去看產(chǎn)品，無(wú)論是C端產(chǎn)品還是B端產(chǎn)品，其實(shí)都是在為用戶提供增、刪、改、查、顯服務(wù)，因此接口需求怎么寫(xiě)，我們可以分別從增、刪、改、查、顯的場(chǎng)景去思考。

1. 查詢

以順豐的運(yùn)費(fèi)失效查詢?yōu)槔嚎蛻粼诩募?，需要預(yù)先運(yùn)費(fèi)時(shí)，可以通過(guò)在運(yùn)費(fèi)時(shí)效查詢中輸入原寄地、目的地，貨物信息（重量、長(zhǎng)、寬、高、件數(shù)）寄件時(shí)間 等信息，可以得出從深圳寄件到武漢的預(yù)估運(yùn)費(fèi)和預(yù)計(jì)時(shí)效。

上圖是通過(guò)F12（瀏覽器檢查工具），查看到的具體請(qǐng)求參數(shù)和返回參數(shù)。

從請(qǐng)求參數(shù)中我們可以發(fā)現(xiàn)，用戶使用運(yùn)費(fèi)時(shí)效查詢工具時(shí)，在用戶界面用戶需要輸入寄件地址的省市區(qū)和收件地址的省市區(qū)，但實(shí)際在執(zhí)行查詢動(dòng)作的時(shí)候是將寄件省市區(qū)和收件省市區(qū)解析為區(qū)號(hào)，然后通過(guò)區(qū)號(hào)去查詢并得到結(jié)果。由此我們可以倒推出，順豐-運(yùn)費(fèi)時(shí)效查詢的接口應(yīng)該如下：

由上面模板可以得知，我們提供給開(kāi)發(fā)的接口需求文檔，主要需要描述以下內(nèi)容：

• 應(yīng)用場(chǎng)景：描述接口的應(yīng)用場(chǎng)景接口描述：描述接口的邏輯，例如運(yùn)費(fèi)單價(jià)查詢邏輯，運(yùn)費(fèi)計(jì)算邏輯等性能：接口的性能要求說(shuō)明，包括調(diào)用量、并發(fā)量等，可以根據(jù)過(guò)去發(fā)生的業(yè)務(wù)量來(lái)評(píng)估；
• 調(diào)用方：接口的調(diào)用方
• 接口CODE：在舊接口中進(jìn)行邏輯調(diào)整，需要把接口CODE附上；新開(kāi)發(fā)的接口，接口CODE可以不寫(xiě)；
• 入?yún)?出參：接口需求中最重要的組成部分之一，在查詢的場(chǎng)景中，可以將入?yún)⒗斫鉃椴樵儣l件；出參理解為期望得到的查詢結(jié)果；如接口需求支持批量查詢，接口的出參需以list的形式返回，并需求說(shuō)明數(shù)據(jù)分頁(yè)規(guī)則

2. 新增

以順豐的運(yùn)單下單業(yè)務(wù)為例：當(dāng)用戶有寄件需求時(shí)，順豐用戶可以在順豐官網(wǎng)、順豐APP、順豐公眾號(hào)、順豐小程序等多個(gè)渠道中任一渠道下單，但從實(shí)現(xiàn)層面來(lái)看，不同渠道的下單業(yè)務(wù)其實(shí)共用的一個(gè)下單接口。

例如，用戶去順豐官網(wǎng)立即下單頁(yè)面， 在寄件表單中分別填寫(xiě)寄方信息、收方信息、快件信息、快遞產(chǎn)品等信息，用戶填寫(xiě)完信息點(diǎn)擊”立即下單”時(shí)調(diào)用下單接口完成下單。

在用戶眼里，填寫(xiě)完寄件信息表單并點(diǎn)擊立即下單，是完成了下單。從系統(tǒng)的角度去理解，實(shí)際是系統(tǒng)基于用戶的行為新增了一條運(yùn)單數(shù)據(jù)。

基于上面的用戶界面截圖可以知道，系統(tǒng)新增一筆運(yùn)單，系統(tǒng)需要用戶填寫(xiě)的寄方信息、收方信息、快件信息、快遞產(chǎn)品等信息，由此可以倒推出順豐新增運(yùn)單的接口為：

3. 修改（更新）

修改（更新）場(chǎng)景的接口，與上面的新增接口類似，以用戶修改賬號(hào)密碼的案例為例：用戶在修改密碼時(shí)，需要在表單中填寫(xiě)賬號(hào)信息和密碼信息，然后點(diǎn)擊【確定】按鈕，提交表單信息并更新賬號(hào)信息。通過(guò)以上的描述，可以倒推出修改賬號(hào)密碼的接口應(yīng)為：

4. 補(bǔ)充說(shuō)明

上面分別從查詢、新增、更新三個(gè)場(chǎng)景舉例說(shuō)明接口需求文檔應(yīng)該怎么寫(xiě)。需特別說(shuō)明的是，一般情況下，僅當(dāng)需求涉及跨業(yè)務(wù)系統(tǒng)的數(shù)據(jù)查詢、新增、更新時(shí)，才需要產(chǎn)品經(jīng)理去做需求調(diào)研并輸出接口需求文檔。

舉個(gè)例子：

在查詢的場(chǎng)景中，如僅僅只是查詢本系統(tǒng)內(nèi)容的數(shù)據(jù)，一般情況下不需要產(chǎn)品經(jīng)理寫(xiě)接口需求文檔。但如果在查詢本系統(tǒng)的數(shù)據(jù)的同時(shí)，需要同時(shí)查其他系統(tǒng)的數(shù)據(jù)，這種場(chǎng)景就涉及到跨業(yè)務(wù)系統(tǒng)的數(shù)據(jù)查詢，需在查詢客戶基礎(chǔ)信息的同時(shí)聯(lián)手另外一個(gè)接口完成信息查詢。

例如：在查詢客戶數(shù)據(jù)的同時(shí)，需要查詢對(duì)應(yīng)客戶在財(cái)務(wù)數(shù)據(jù)中的充值余額數(shù)據(jù)，此時(shí)就需要一個(gè)根據(jù)客戶查詢財(cái)務(wù)數(shù)據(jù)中對(duì)應(yīng)個(gè)客戶的充值余額數(shù)據(jù)的接口，來(lái)聯(lián)合實(shí)現(xiàn)在查詢客戶基礎(chǔ)數(shù)據(jù)的同時(shí)查詢對(duì)應(yīng)客戶財(cái)務(wù)數(shù)據(jù)的功能需求，接口示例如下：

四、總結(jié)

對(duì)于接口：產(chǎn)品經(jīng)理最好能有一定程度的理解，它可以幫助產(chǎn)品經(jīng)理更深一層理解產(chǎn)品功能實(shí)現(xiàn)背后的事；雖然并不是所有的公司都會(huì)要求產(chǎn)品經(jīng)理寫(xiě)接口需求，也并不是所有的需求過(guò)程中需求產(chǎn)品經(jīng)理接口需求，但產(chǎn)品經(jīng)理最好能理解并掌握如何處理接口需求。

在產(chǎn)品功能的實(shí)現(xiàn)的背后，后端服務(wù)與用戶界面的交互、不同業(yè)務(wù)系統(tǒng)之間的交互都會(huì)用到API（接口）。以上這些內(nèi)容是產(chǎn)品經(jīng)理視角對(duì)產(chǎn)接口的理解。如從開(kāi)發(fā)的角度去討論接口，遠(yuǎn)不止這些。

作者：汪童學(xué)；公眾號(hào)：汪童學(xué)

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

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