在日常工作中，產(chǎn)品經(jīng)理需要與多方進(jìn)行溝通協(xié)作，那么掌握相關(guān)基礎(chǔ)知識(shí)對(duì)于雙方的溝通能夠更加順暢。本文總結(jié)了新手產(chǎn)品經(jīng)理必學(xué)技術(shù)接口文檔知識(shí)，方便進(jìn)一步與開發(fā)技術(shù)進(jìn)行協(xié)作，希望對(duì)你有所幫助。

產(chǎn)品經(jīng)理需不需要懂技術(shù)接口文檔？這個(gè)問題我覺得就跟問產(chǎn)品經(jīng)理需不需要懂技術(shù)是一樣的，而我的建議是，需要懂，但只需要有限度地懂。今天我結(jié)合之前的一些項(xiàng)目經(jīng)驗(yàn)，以對(duì)接電子發(fā)票中的開具發(fā)票接口為例，分享產(chǎn)品經(jīng)理怎么學(xué)會(huì)看懂技術(shù)接口文檔。

本文是以產(chǎn)品經(jīng)理理解的角度去說明和解構(gòu)接口文檔，可能在技術(shù)角度未必是正確的，如果有臥底的開發(fā)大佬，還請(qǐng)勿噴！

一、什么是接口文檔

要學(xué)會(huì)看接口文檔，首先得明白什么是接口文檔，接口文檔的作用是什么。

隨著開發(fā)技術(shù)的發(fā)展，漸漸發(fā)展成為前后端分離的開發(fā)方式，簡(jiǎn)單講就是前端開發(fā)工程師和后端開發(fā)工程師各自開發(fā)屬于自己范圍的內(nèi)容，最后通過 api 接口來進(jìn)行前后端信息的傳遞，而接口文檔就是記錄各個(gè)不同業(yè)務(wù)用到的 api 接口以及它們所傳遞的信息的技術(shù)文檔。但這種文檔一般是內(nèi)部用的，因此可以說是純粹為了開發(fā)服務(wù)，產(chǎn)品經(jīng)理基本接觸不到。

后來，隨著業(yè)務(wù)形態(tài)的發(fā)展，在某些業(yè)務(wù)領(lǐng)域或技術(shù)領(lǐng)域有較強(qiáng)優(yōu)勢(shì)的公司會(huì)通過出售自身能力來獲得銷售的收入，比如支付能力、視頻流媒體能力、AI 能力等，使得購買的公司能夠以最快的方式實(shí)現(xiàn)相應(yīng)的能力，而實(shí)現(xiàn)這種能力的方式之一，就是通過開放 api 接口來進(jìn)行對(duì)接，接口文檔可以讓產(chǎn)品經(jīng)理和開發(fā)工程師快速對(duì)接業(yè)務(wù)和技術(shù)。

這么講可能有點(diǎn)抽象，舉個(gè)例子，比如我現(xiàn)在有一個(gè)商城產(chǎn)品，需要使用移動(dòng)支付，但是我自己沒有金融牌照，不能做在線收款的業(yè)務(wù)，而某公司有金融牌照，可以開發(fā)在線支付的功能并進(jìn)行在線收款，該公司通過開放相關(guān)的技術(shù)接口，商城只需要按照接口對(duì)接完成，由該公司來進(jìn)行代收代付，即可完成在線收款的功能，當(dāng)然，該公司在此過程中可能會(huì)收取相應(yīng)的費(fèi)用，這種是屬于有業(yè)務(wù)領(lǐng)域優(yōu)勢(shì)的類型。

另外一個(gè)例子，比如商城需要做一個(gè)在線直播的功能，但是目前公司沒有在線視頻流媒體等技術(shù)的專業(yè)開發(fā)人員和技術(shù)積累，而某公司則是在這方面有著多年的經(jīng)驗(yàn)和深厚的技術(shù)積累，因此我們可以購買接入該公司的服務(wù)，快速實(shí)現(xiàn)在線直播的功能，這種，則是屬于有技術(shù)領(lǐng)域優(yōu)勢(shì)的類型。

二、接口工作原理

以下圖片可以幫助我們理解接口的工作原理：

我舉一個(gè)例子，比如【接口開放方】開放了一個(gè)接口，接口名稱為【你好】，接口要求提供【姓名】作為參數(shù)，并返回【某某某，你好】的內(nèi)容，其中【某某某】是請(qǐng)求接口時(shí)提供的【姓名】。

接口的交互用戶是無法感知的，所以需要在用戶端處理內(nèi)容的輸入和輸出，比如在網(wǎng)頁上放一個(gè)輸入框，讓用戶輸入姓名，假設(shè)用戶輸入【李雷】，點(diǎn)擊確認(rèn)，這個(gè)時(shí)候，【接口請(qǐng)求方】請(qǐng)求【你好】這個(gè)接口，并傳遞姓名【李雷】，接下來就會(huì)收到【接口開放方】響應(yīng)回來的信息【李雷，你好】，此時(shí)再將收到的這句話通過彈窗之類的形式在用戶端顯示出來，這樣就完成了一次接口的調(diào)用。

【接口請(qǐng)求方】無需理會(huì)【接口開放方】?jī)?nèi)部的實(shí)現(xiàn)方法，只需關(guān)注收到響應(yīng)后如何處理響應(yīng)即可（如上方例子中的將收到的信息通過彈窗形式顯示出來），而處理響應(yīng)一般涉及業(yè)務(wù)相關(guān)，所以需要產(chǎn)品經(jīng)理介入，因此產(chǎn)品經(jīng)理看文檔的時(shí)候，需要知道，某個(gè)接口是為了實(shí)現(xiàn)什么功能（比如上方的“你好”接口會(huì)返回問好的文字），需要提供什么參數(shù)（如上方的“姓名”），會(huì)響應(yīng)什么參數(shù)（如上方的“某某某，你好”的信息），收到響應(yīng)后要怎么處理（一般跟接入方的業(yè)務(wù)有關(guān)）。

三、常規(guī)接入流程

這里講的是常規(guī)的接入流程，不代表所有平臺(tái)都是以這樣的方式接入，以下是接入流程示意圖：

不是拿到接口文檔就可以接入，剛剛提到，接口提供方可能會(huì)按照某種方式來收取一定的費(fèi)用，所以接口的使用肯定是需要在接口開放方的授權(quán)下才能進(jìn)行，所以在完成商務(wù)談判之后，一般接口提供方會(huì)要求接入方在他們平臺(tái)注冊(cè)賬號(hào)，并通過技術(shù)手段給接入放分配相關(guān)簽名參數(shù)。

簽名參數(shù)有兩種作用：

1. 獲得接入權(quán)限，相當(dāng)于鑰匙；
2. 攜帶身份信息，相當(dāng)于身份證。

所以簽名參數(shù)可以理解為是帶有身份信息的通行證，有了簽名參數(shù)，才能夠正常請(qǐng)求接口，并且每次請(qǐng)求，接口提供方都能知道是誰發(fā)起了接口請(qǐng)求。

四、怎么看接口文檔

剛剛講的都是一些純理論的東西，接下來我以某電子發(fā)票平臺(tái)的接口文檔為例，講講如果我所在的平臺(tái)需要增加一個(gè)開具電子發(fā)票的功能，在收到接口文檔之后，要怎么看。

這是接口文檔的目錄，在收到文檔之后，建議先看介紹，這里面一般會(huì)涉及到當(dāng)前對(duì)接的這個(gè)產(chǎn)品的說明、實(shí)現(xiàn)功能、適用場(chǎng)景等，產(chǎn)品經(jīng)理需要結(jié)合自身產(chǎn)品的業(yè)務(wù)分析要對(duì)接的產(chǎn)品的功能和適用場(chǎng)景是否符合公司想要實(shí)現(xiàn)的業(yè)務(wù)。

接下來是【調(diào)用方式】中的【簽名方法】，這個(gè)需要分情況，如果你的平臺(tái)是自己對(duì)接，自己使用，作為產(chǎn)品經(jīng)理可以不用看這塊，但是如果你做的 SaaS 系統(tǒng)，你的平臺(tái)可能會(huì)入駐多名商戶，每名商戶都需要去接口提供方平臺(tái)注冊(cè)并提供簽名參數(shù)，你不可能每次有新入駐的商戶就讓開發(fā)工程師往數(shù)據(jù)庫里加數(shù)據(jù)，最合理的解決方案就是在后臺(tái)設(shè)計(jì)一個(gè)商戶管理功能，在商戶管理功能中增加簽名參數(shù)的填寫，這個(gè)時(shí)候，作為產(chǎn)品經(jīng)理你就必須得知道，這個(gè)平臺(tái)需要提供哪些簽名參數(shù)，從而支撐你完成這塊功能的設(shè)計(jì)，比如這個(gè)發(fā)票平臺(tái)的簽名參數(shù)要求提供以下4個(gè)參數(shù)：

那么你在設(shè)計(jì)時(shí)，就需要提供相應(yīng)參數(shù)的輸入。

接下來是“主菜”，在 api 列表中，一般會(huì)按照不同的業(yè)務(wù)功能劃分不同的接口，并以對(duì)應(yīng)的業(yè)務(wù)描述來命名接口，因此，我們?nèi)绻O(shè)計(jì)開具發(fā)票的功能，需要先找到對(duì)應(yīng)的接口：

點(diǎn)擊對(duì)應(yīng)接口后，就可以看到接口的詳情，以下是作為產(chǎn)品經(jīng)理需要關(guān)注的幾個(gè)點(diǎn)：

口說明：這里面一般會(huì)有一些比較重要的信息，一定要先仔細(xì)閱讀，有些產(chǎn)品經(jīng)理一上來就跳過接口說明的內(nèi)容，直接看接口參數(shù)，然后遇到問題解決不了，一直在原地轉(zhuǎn)圈，結(jié)果發(fā)現(xiàn)人家已經(jīng)在接口說明中說了會(huì)遇到什么問題，是什么原因，怎么解決。

請(qǐng)求參數(shù)：這個(gè)是產(chǎn)品經(jīng)理需要重點(diǎn)關(guān)注的內(nèi)容，這里面涉及到在調(diào)用這個(gè)接口的時(shí)候需要提供什么參數(shù)，這些參數(shù)往往都是用戶輸入的，因此產(chǎn)品經(jīng)理需要根據(jù)所需參數(shù)在用戶端收集相應(yīng)的信息，如以下關(guān)于開具發(fā)票接口的部分請(qǐng)求參數(shù)：

這里面我們要關(guān)注的，主要是【是否必填】以及【描述】，描述中會(huì)說明這個(gè)參數(shù)是什么，有什么要求，這里一定要區(qū)分好哪些參數(shù)是技術(shù)需要的，哪些參數(shù)是業(yè)務(wù)需要的，產(chǎn)品經(jīng)理要重點(diǎn)關(guān)注業(yè)務(wù)參數(shù)，如果不清楚參數(shù)的用途，可以找接口提供方的提供幫助。

有一些相應(yīng)的校驗(yàn)需要產(chǎn)品經(jīng)理在用戶端收集信息的時(shí)候就做好要求，防止提交給接口的參數(shù)是不符合要求的，這樣會(huì)浪費(fèi)網(wǎng)絡(luò)資源（每次請(qǐng)求都需要等待回復(fù)，如果多次嘗試失敗，會(huì)讓用戶覺得體驗(yàn)不好），甚至浪費(fèi)金錢（有些平臺(tái)會(huì)按照接口請(qǐng)求的次數(shù)收費(fèi)，請(qǐng)求一次扣一次費(fèi)用）。

響應(yīng)參數(shù)：這是請(qǐng)求接口之后，接口提供方回傳給我們的參數(shù)，一般會(huì)包含狀態(tài)和對(duì)應(yīng)的參數(shù)，如下是開具發(fā)票的響應(yīng)參數(shù)：

但是這里有點(diǎn)奇怪，我們?nèi)绻暾?qǐng)開具電子發(fā)票，至少要把電子發(fā)票的文件給我們吧，不然我們?cè)醢盐募o用戶，這時(shí)候我們仔細(xì)看一下，原來開票的接口是通過異步通知我們的，這里就需要區(qū)分什么同步什么是異步了。

一般我們提交之后，可以馬上反饋給我們的就是同步通知，比如這里的狀態(tài)，告訴我們已經(jīng)提交成功了或者已經(jīng)開過票了。而異步通知是說，我們請(qǐng)求的這個(gè)接口需要的一部分內(nèi)容，需要等待接口提供方處理，處理完之后再告訴我們結(jié)果，比如這里，開具發(fā)票申請(qǐng)?zhí)峤怀晒Γ情_票平臺(tái)需要同步稅務(wù)局的系統(tǒng)進(jìn)行開票，這里需要有一個(gè)處理的時(shí)間，要等它處理完之后再告訴我們結(jié)果。

我們可以找一下，發(fā)現(xiàn)接口文檔中確實(shí)有一個(gè)【開票接口異步通知】的接口，點(diǎn)開發(fā)現(xiàn)這里返回的參數(shù)就非常多了，包括開票的狀態(tài)，電子發(fā)票開票成功后電子發(fā)票的url等，收到相應(yīng)的響應(yīng)信息之后，我們需要只需要處理對(duì)應(yīng)的信息即可，比如前端可能需要更新開票的狀態(tài)，或者顯示電子發(fā)票的下載入口等。

以上是個(gè)人的經(jīng)驗(yàn)之談，希望能夠?qū)側(cè)胄械漠a(chǎn)品經(jīng)理學(xué)習(xí)閱讀接口文檔有一定幫助，感謝閱讀！