2023年【經(jīng)驗分享】新手產(chǎn)品經(jīng)理必學技術(shù)接口文檔知識

【經(jīng)驗分享】新手產(chǎn)品經(jīng)理必學技術(shù)接口文檔知識產(chǎn)品經(jīng)理需不需要懂技術(shù)接口文檔？這個問題我覺得就跟問產(chǎn)品經(jīng)理需不需要懂技術(shù)是一樣的，而我的建議是，需要懂，但只需要有限度地懂。今日我結(jié)合之前的一些項目閱歷，以對接電子發(fā)票中的開具發(fā)票接口為例，共享產(chǎn)品經(jīng)理怎么學會看懂技術(shù)接口文檔。

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

一、什么是接口文檔

要學會看接口文檔，首先得明白什么是接口文檔，接口文檔的作用是什么。

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

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

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

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

二、接口工作原理

以下圖片可以關(guān)心我們理解接口的工作原理：

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

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

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

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

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

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

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

獲得接入權(quán)限，相當于鑰匙；攜帶身份信息，相當于身份證。所以簽名參數(shù)可以理解為是帶有身份信息的通行證，有了簽名參數(shù)，才能夠正常懇求接口，并且每次懇求，接口供應方都能知道是誰發(fā)起了接口懇求。

四、怎么看接口文檔

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

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

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

那么你在設(shè)計時，就需要供應相應參數(shù)的輸入。

接下來是“主菜”，在api列表中，一般會根據(jù)不同的業(yè)務(wù)功能劃分不同的接口，并以對應的業(yè)務(wù)描述來命名接口，因此，我們假如要設(shè)計開具發(fā)票的功能，需要先找到對應的接口：

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

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

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

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

有一些相應的校驗需要產(chǎn)品經(jīng)理在用戶端收集信息的時候就做好要求，防止提交給接口的參數(shù)是不符合要求的，這樣會鋪張網(wǎng)絡(luò)資源（每次懇求都需要等待回復，假如多次嘗試失敗，會讓用戶覺得體驗不好），甚至鋪張金錢（有些平臺會根據(jù)接口懇求的次數(shù)收費，懇求一次扣一次費用）。

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

但是這里有點驚奇，我們假如申請開具電子發(fā)票，至少要把電子發(fā)票的文件給我們吧，不然我們怎把文件給用戶，這時候我們認真看一下，原來開票的接口是通過異步通知我們的，這里就需要區(qū)分什么同步什么是異步了。

一般我們提交之后，可以立刻反饋給我們的就是同步通知，比如這里的狀態(tài)，告知我們已經(jīng)提交勝利了或者已經(jīng)開過票了。而異步通知是說，我們懇求的這個接口需要的一部分內(nèi)容，需要等待接口供應方處理，處理完之后再告知我們結(jié)果，比如這里，開具發(fā)票申請?zhí)峤粍倮?，但是開票平臺需要同步稅務(wù)局的系統(tǒng)進行開票，這里需要有一個處理的時間，要等它處理完之后再告知我們結(jié)果。

我們可以找一下，發(fā)覺接口文檔中的確有一個【開票接