作為一個(gè)產(chǎn)品經(jīng)理，要如何輕松搞定接口需求與文檔？下面一起來(lái)看這篇有筆者整理分享的關(guān)于接口需求與文檔相關(guān)內(nèi)容的文章吧！推薦值得一看哦！

一、前言

不懂技術(shù)的產(chǎn)品同學(xué)，天然的對(duì)技術(shù)相關(guān)的需求犯怵。比如說(shuō)接口需求，接口是開發(fā)過程中避免不了的東西，作為產(chǎn)品經(jīng)理，一定要知道。我一直負(fù)責(zé)集團(tuán)的公共服務(wù)，所有服務(wù)都是通過「接口」與各個(gè)產(chǎn)品線對(duì)接。我也沒有技術(shù)背景，當(dāng)然在過程中遇到了一些問題，所以我總結(jié)了關(guān)于「接口需求」相關(guān)的內(nèi)容。

說(shuō)下：接口需求怎么提接口文檔怎么看。

二、接口的作用

什么是接口？

看下邊的例子：

微信獲取用戶基礎(chǔ)信息接口：https://api.weixin.qq.com/cgi-bin/user/info/batchget?access_token=ACCESS_TOKEN

飛書查看全部工單接口：https://open.feishu.cn/open-apis/helpdesk/v1/tickets

這些 url鏈接就是接口地址。通過調(diào)用接口地址，獲取到想要的東西。對(duì)于接口的作用，我劃分為 3 種：

1. 前端與后端的數(shù)據(jù)處理

比如列表上有個(gè)「新增」的功能。前端開發(fā)出一個(gè)表單功能，當(dāng)填完數(shù)據(jù)后，點(diǎn)擊確定，前端會(huì)調(diào)用「新增數(shù)據(jù)接口」，將頁(yè)面中錄入的數(shù)據(jù)通過接口，傳給后端，后端對(duì)傳入的數(shù)據(jù)進(jìn)行處理。接口處理完成后，會(huì)返回出具體的參數(shù)，前端根據(jù)返回的參數(shù)，給出對(duì)應(yīng)的反饋信息。

比如當(dāng)接口的校驗(yàn)沒有通過時(shí)，則會(huì)通過接口返回出錯(cuò)誤信息，前端會(huì)將錯(cuò)誤信息在頁(yè)面上進(jìn)行提示。

同樣的，對(duì)于刪除數(shù)據(jù)、修改數(shù)據(jù)、查詢數(shù)據(jù)等，都是通過接口的方式對(duì)數(shù)據(jù)進(jìn)行處理。

2. 跨系統(tǒng)的同步數(shù)據(jù)

兩個(gè)系統(tǒng)之間進(jìn)行數(shù)據(jù)同步。

比如我有個(gè)需求，需要使用到「系統(tǒng)用戶信息」。對(duì)于「用戶信息」，我司只有「賬號(hào)系統(tǒng)」有，我需要和賬號(hào)系統(tǒng)的產(chǎn)品經(jīng)理溝通，對(duì)方提供給我一個(gè)接口文檔，我們按照接口文檔的要求進(jìn)行數(shù)據(jù)同步。

同樣的，當(dāng)有需求要使用到你系統(tǒng)里的數(shù)據(jù)，也可以通過「接口」將數(shù)據(jù)同步給需求方。對(duì)于數(shù)據(jù)同步接口，數(shù)據(jù)同步的方式、數(shù)據(jù)同步的時(shí)機(jī)等等都是接口需求需要考慮到的內(nèi)容。

這幾點(diǎn)我們?cè)谙逻呍敿?xì)說(shuō)～

3. 提供公共服務(wù)

通過接口對(duì)外提供服務(wù)能力，可以滿足不同的系統(tǒng)或應(yīng)用程序之間進(jìn)行功能調(diào)用。比如說(shuō)身份證歸屬地查詢服務(wù)，通過輸入身份證號(hào)查詢出歸屬地。當(dāng)需要使用這個(gè)功能的時(shí)候，都可以調(diào)用「身份證歸屬地查詢接口」，來(lái)實(shí)現(xiàn)這個(gè)功能。

另外支付服務(wù)、登錄服務(wù)、獲取收貨地址等等，能夠?qū)ν馓峁┑墓卜?wù)，我們都可以做成公共接口對(duì)外使用。

三、接口需求怎么提

很多同學(xué)認(rèn)為接口是研發(fā)開發(fā)的，和產(chǎn)品沒有關(guān)系，我之前也是這樣想，后來(lái)發(fā)現(xiàn)這個(gè)并不對(duì)。接口是基于需求來(lái)開發(fā)的，里邊涉及業(yè)務(wù)相關(guān)的內(nèi)容，研發(fā)并不清楚具體的業(yè)務(wù)場(chǎng)景，如果產(chǎn)品經(jīng)理不進(jìn)行介入，就會(huì)導(dǎo)致接口的場(chǎng)景覆蓋程度、擴(kuò)展性受限。

不會(huì)提接口需求沒關(guān)系，我們接下來(lái)細(xì)說(shuō)：我們根據(jù)上邊說(shuō)的3 種接口用途，看下需求如何提。

1. 前后端數(shù)據(jù)處理接口

這類接口一般和功能相關(guān)，也不涉及到跨系統(tǒng)，可以直接通過功能需求描述，不用特意地對(duì)接口進(jìn)行說(shuō)明。在研發(fā)開始前，前端與后端根據(jù)需求進(jìn)行功能拆分，后端開發(fā)接口，前端開發(fā)頁(yè)面，然后前后端進(jìn)行接口聯(lián)調(diào)。

2. 數(shù)據(jù)同步接口

無(wú)非 2 種：

1. 你向別人提供數(shù)據(jù)：需要你定義接口需求
2. 別人向你提供數(shù)據(jù)：需要你會(huì)看別人的接口文檔

我們先看「你向別人提供數(shù)據(jù)」

舉個(gè)例子：一條產(chǎn)品線有個(gè)需求，想使用你系統(tǒng)的「人員信息」數(shù)據(jù)，在他們系統(tǒng)的頁(yè)面中展示出「人員信息列表」

我們先從以下角度思考：

1）數(shù)據(jù)能否提供？

1. 是否該由自己系統(tǒng)提供，是否其他系統(tǒng)提供更好？
2. 提供的數(shù)據(jù)能夠滿足對(duì)方需求，是否缺字段？
3. 數(shù)據(jù)是否敏感數(shù)據(jù)？是否知識(shí)產(chǎn)權(quán)數(shù)據(jù)？
4. 其它產(chǎn)品線是否也有這個(gè)需求，是否也需要這個(gè)接口？
5. 對(duì)于這個(gè)接口是做成公共接口，每個(gè)業(yè)務(wù)方都能進(jìn)行調(diào)用，還是只對(duì)這一個(gè)業(yè)務(wù)線提供。

一般情況下，數(shù)據(jù)同步接口都可以做成公共接口，讓每個(gè)業(yè)務(wù)方都能使用此接口。

2）支持哪種同步方式？

①業(yè)務(wù)方直接使用接口實(shí)時(shí)搜索，直接列表展示

業(yè)務(wù)方通過接口實(shí)時(shí)查詢數(shù)據(jù)，并展示出結(jié)果，不將數(shù)據(jù)放到自己的數(shù)據(jù)庫(kù)里。好處是每次查詢都是最新數(shù)據(jù)。但是這種方式很不建議，當(dāng)有業(yè)務(wù)方需要用到你的數(shù)據(jù)的時(shí)候，也需要提醒對(duì)方不要使用這種方式。用他方的數(shù)據(jù)同步接口去進(jìn)行實(shí)時(shí)查詢，如果數(shù)據(jù)同步接口性能扛不住，接口掛了，那業(yè)務(wù)也會(huì)掛。

當(dāng)需要對(duì)數(shù)據(jù)進(jìn)行二次加工處理，這種方式就不支持了，只能讓數(shù)據(jù)同步接口加需求。但是一般的數(shù)據(jù)同步接口都是公共接口，不僅有一個(gè)業(yè)務(wù)方使用，當(dāng)這個(gè)接口不滿足你的需求的時(shí)候，公共接口不會(huì)根據(jù)你的需求做個(gè)性化調(diào)整。

②業(yè)務(wù)方通過接口將數(shù)據(jù)存儲(chǔ)到自己的數(shù)據(jù)庫(kù)中，對(duì)數(shù)據(jù)進(jìn)行二次處理

通過數(shù)據(jù)同步接口，將數(shù)據(jù)同步到自己的數(shù)據(jù)庫(kù)中，單獨(dú)存一份，與數(shù)據(jù)提供方做一層隔離。自己業(yè)務(wù)使用時(shí)，從自己的數(shù)據(jù)庫(kù)中取數(shù)據(jù)。這樣就算同步接口掛了，也不會(huì)影響自己的業(yè)務(wù)。同時(shí)，可以對(duì)獲取的數(shù)據(jù)進(jìn)行二次處理，靈活性更強(qiáng)。當(dāng)業(yè)務(wù)方單獨(dú)存儲(chǔ)數(shù)據(jù)后，為了讓兩方數(shù)據(jù)保持一致，這就涉及到「數(shù)據(jù)更新」。

3）數(shù)據(jù)更新機(jī)制

分為2種：推、拉

推：有數(shù)據(jù)更新后，將更新的數(shù)據(jù)推給下游業(yè)務(wù)方。

①「推」有 2 種方式：

1. 當(dāng)數(shù)據(jù)有更新時(shí)，上游給下游業(yè)務(wù)方發(fā)一條「數(shù)據(jù)更新通知」，讓業(yè)務(wù)方判斷是否更新、更新哪些數(shù)據(jù)。這個(gè)時(shí)候上游就需要多開發(fā)一個(gè)「數(shù)據(jù)更新通知接口」，用于發(fā)出通知。同時(shí)下游方也需要開發(fā)一個(gè)接口，用于接收通知。
2. 強(qiáng)制業(yè)務(wù)方更新，硬性更新數(shù)據(jù)。對(duì)于主數(shù)據(jù)、標(biāo)準(zhǔn)字典值都需要使用這種方式。

拉：下游業(yè)務(wù)方去主動(dòng)拉取新的數(shù)據(jù)。

②「拉取」有 2 種方式：

1. 定時(shí)拉?。河沙绦蚨〞r(shí)拉取，如每天同步、每 5min 同步、每 1h 同步一次等等，根據(jù)數(shù)據(jù)更新頻次、對(duì)數(shù)據(jù)一致性的嚴(yán)謹(jǐn)度進(jìn)行判斷。
2. 手動(dòng)拉?。菏謩?dòng)觸發(fā)更新。是指當(dāng)需要使用到最新數(shù)據(jù)的時(shí)候，手動(dòng)觸發(fā)數(shù)據(jù)更新，比如頁(yè)面上添加個(gè)「數(shù)據(jù)同步」的按鈕，點(diǎn)擊后，調(diào)用數(shù)據(jù)同步接口，拉取最新的數(shù)據(jù)。當(dāng)然，也可以「定時(shí)拉取+手動(dòng)拉取」，例如每晚程序自動(dòng)更新，白天需要更新時(shí)，可手動(dòng)觸發(fā)更新。每次更新數(shù)據(jù)的時(shí)候，又涉及到「數(shù)據(jù)更新的范圍」。

4）數(shù)據(jù)更新范圍

分為：全量更新、增量更新。它們的選擇取決于需要同步的數(shù)據(jù)量以及更新的頻率。

• 全量更新：更新全部數(shù)據(jù)，無(wú)論數(shù)據(jù)是否有變化，都會(huì)對(duì)整個(gè)數(shù)據(jù)進(jìn)行更新。將已有的數(shù)據(jù)刪除，然后重新獲取新的數(shù)據(jù)。這種方式比較適合數(shù)據(jù)量較小或?qū)?shù)據(jù)一致性要求較高的情況。
• 增量更新：只更新發(fā)生變化的數(shù)據(jù)。當(dāng)把數(shù)據(jù)全量同步后，之后只更新發(fā)生變化的數(shù)據(jù)。比如說(shuō)上游發(fā)出了數(shù)據(jù)更新通知，告訴哪條數(shù)據(jù)發(fā)生了更新，此時(shí)接入方可以只更新發(fā)生更新的數(shù)據(jù)。增量更新適用于整體數(shù)據(jù)量較大、更新頻率低的情況。增量更新比較高效，更新數(shù)據(jù)用時(shí)也比較快。到這，我們把數(shù)據(jù)同步的同步方式、數(shù)據(jù)更新機(jī)制、數(shù)據(jù)更新范圍確定好了。接著繼續(xù)明確接入方可以使用哪些字段去獲取數(shù)據(jù)。

5）通過哪些字段獲取數(shù)據(jù)能獲取到哪些數(shù)據(jù)？

用哪個(gè)字段獲取數(shù)據(jù)，意思是向接口傳入哪些字段。能夠獲取到哪些數(shù)據(jù)，意思是接口會(huì)返回出哪些字段。會(huì)有2 個(gè)名詞：

1. 入?yún)ⅲ壕褪窍蚪涌趥魅氲膮?shù)數(shù)據(jù)，也叫請(qǐng)求參數(shù)等。
2. 出參：接口返回?cái)?shù)據(jù)的參數(shù)數(shù)據(jù)，也叫返參、返回參數(shù)、響應(yīng)參數(shù)等。

你可以理解為，接口就是個(gè)列表，這個(gè)列表的查詢條件有哪些、查詢結(jié)果有哪些。查詢條件，就是接口的「入?yún)ⅰ共樵兂龅慕Y(jié)果，就是接口的「出參」

①對(duì)于「入?yún)ⅰ?，在提需求時(shí)，產(chǎn)品經(jīng)理需要考慮到：

1. 入?yún)⒂心男┳侄危烤褪沁@個(gè)列表的查詢條件是什么？比如我們需要對(duì)外同步「人員信息」，可以通過「人員 ID」進(jìn)行獲取數(shù)據(jù)，也可以通過「性別」，只獲取性別為「男」的數(shù)據(jù)。人員ID、性別就是這個(gè)接口的入?yún)ⅰ?/li>
2. 入?yún)⒆侄蔚母袷绞鞘裁?？格式是指字段是字符串、日期格式還是字典值等。比如說(shuō)「人員性別」，可以定義成 0，1。0 代表女性、1 代表男性。也可以是文字「女性、男性」。對(duì)于字段格式，產(chǎn)品經(jīng)理主要是提供建議，具體的還是以研發(fā)為準(zhǔn)。
3. 入?yún)⒆侄文軌蛑С峙坎樵?？可以理解為查詢條件的字段是不是支持多選。比如說(shuō)「人員性別」，是可以通過下拉框多選，還是每次只能選擇一個(gè)。
4. 入?yún)⒆侄问遣皇潜靥?？比如說(shuō)查詢時(shí)，必須輸入「人員 ID」，否則就不支持查詢。

②對(duì)于「出參」，產(chǎn)品經(jīng)理需要考慮到：

1. 出參字段有哪些？也就是查詢結(jié)果需要有什么？比如出參有：人員 ID、人員姓名、人員性別、創(chuàng)建時(shí)間、創(chuàng)建人、更新時(shí)間、更新人、是否啟用、是否刪除。
2. 出參字段的格式是什么？這個(gè)和「入?yún)ⅰ瓜嗤?，產(chǎn)品經(jīng)理給出參考建議。然后，在提需求的時(shí)候，我們可以通過表格的形式說(shuō)明「入?yún)?、出參」?/li>

③入?yún)⑹纠纾?/p>

④出參示例如：

到這里，我們的數(shù)據(jù)同步接口需求就可以了，更詳細(xì)的可以看我提供的真實(shí)接口需求示例，領(lǐng)取方式在文末。

3. 服務(wù)用接口

這個(gè)接口也比較常見，在很多服務(wù)對(duì)接時(shí)，都是直接使用接口對(duì)接。產(chǎn)品經(jīng)理需要確定的接口中與業(yè)務(wù)相關(guān)的內(nèi)容。

主要包括入?yún)?、出參、接口處理邏輯?/p>

1. 對(duì)于入?yún)ⅲ盒枰呀涌谥械娜雲(yún)⒆侄斡心男┱f(shuō)清楚。不僅要把接口處理必須用到的字段說(shuō)清楚，對(duì)于之后接口用到的字段，也可以寫出來(lái)。業(yè)務(wù)方在第一次接入的時(shí)候，把能傳入的字段都傳過來(lái)，下次接口新增其他服務(wù)的時(shí)候，可以直接用，不需要業(yè)務(wù)方在調(diào)整接口。
2. 對(duì)于出參：需要把接口返參中的字段進(jìn)行說(shuō)明。原因是返參的字段，才是要最終用到業(yè)務(wù)上的，需要產(chǎn)品經(jīng)理確定有哪些字段，并把字段進(jìn)行說(shuō)明。
3. 接口處理邏輯：就是接口通過「入?yún)ⅰ褂?jì)算出「返參」的具體邏輯，包括校驗(yàn)邏輯等一系列處理邏輯。

說(shuō)個(gè)簡(jiǎn)單的例子：通過「身份證號(hào)查詢歸屬地服務(wù)」

既然是通過「身份證號(hào)」查詢，那「入?yún)ⅰ估锟隙ň褪恰干矸葑C號(hào)」

「返參」里有歸屬地，那「歸屬地」就涉及到省、市、區(qū)。

需求可以這樣提：

1）入?yún)ⅲ?/strong>身份證號(hào)、必填、字符串、長(zhǎng)度18位