編輯指南：為了便于開發(fā)和產(chǎn)品溝通，有接口文檔。

接口文檔大多時(shí)候是給開發(fā)看的，那么產(chǎn)品為什么要會(huì)看接口文檔呢？本文作者對(duì)此發(fā)表了自己的看法，一起來(lái)看看吧。

又到了周末，快樂(lè)開黑開始！阿宅興沖沖得找小伙伴上號(hào)，結(jié)果小伙伴爾康擺手：“等一下，我先開電腦噴下開發(fā)?！?/p>

阿宅一局酣戰(zhàn)之后，又來(lái)找到小伙伴：“好了沒(méi)？”“沒(méi)好，我被開發(fā)噴了，是我的需求bug，老板還罵我了，你看?！?/p>

為了讓小伙伴盡快上號(hào)，我們開始一起復(fù)盤：“這是關(guān)于基金購(gòu)買流程的需求，我在這個(gè)地方需要先明確基金的委托類型，我問(wèn)爺爺找爸爸終于把這個(gè)理清楚了，可以分為購(gòu)買、贖回、定投。結(jié)果上線后才發(fā)現(xiàn)分類沒(méi)定義完整?！薄斑@玩意不是接口里寫得明明白白嗎？”

“?。。?！接口文檔是個(gè)啥！我怎么從來(lái)沒(méi)看過(guò)！”

“你啊你，都做了半年理財(cái)產(chǎn)品了，竟然連這個(gè)都不知道。那本宅就大發(fā)慈悲教教你吧，記住明天給我一根冰糖葫蘆?！?/p>

一、什么是接口文檔？

首先，什么是接口？你可以把它簡(jiǎn)單理解為一個(gè)函數(shù)，你輸入x，它就會(huì)告訴你y。你無(wú)需知道這個(gè)函數(shù)的邏輯，只需要知道輸入什么樣的問(wèn)題，會(huì)得到什么樣的答案就可以了。

但x怎么輸，會(huì)出現(xiàn)什么樣的y，就需要通過(guò)接口文檔來(lái)了解。就比如下圖的表格，當(dāng)你按照“輸入?yún)?shù)”輸入“委托方式”、“分支機(jī)構(gòu)”等參數(shù)時(shí)，這個(gè)接口就會(huì)告訴你“資產(chǎn)賬戶”是什么。

恒生統(tǒng)一接入平臺(tái)_周邊接口規(guī)范(期貨,期權(quán)_20210812).xls

二、產(chǎn)品為什么要能看懂接口文檔？

接口一般來(lái)講分為兩種：

• 程序內(nèi)部的接口：方法與方法、模塊與模塊之間的交互，如登錄發(fā)帖，發(fā)帖就必須要登錄，如果不登錄不能發(fā)帖，發(fā)帖和登錄這兩個(gè)模塊之間就要有交互，就會(huì)拋出一個(gè)接口，進(jìn)行內(nèi)部系統(tǒng)調(diào)用。
• 系統(tǒng)對(duì)外的接口：從別人的網(wǎng)站或服務(wù)器上獲取資源或信息，對(duì)方不會(huì)提供數(shù)據(jù)庫(kù)，只能提供一個(gè)寫好的方法來(lái)獲取數(shù)據(jù)，如購(gòu)物網(wǎng)站和第三方支付，購(gòu)物網(wǎng)站支付時(shí)可選擇第三方支付方法，但第三方不會(huì)提供自己的數(shù)據(jù)庫(kù)給購(gòu)物網(wǎng)站，只會(huì)提供一個(gè)接口，供購(gòu)物網(wǎng)站進(jìn)行調(diào)用。

這便意味著開發(fā)的人甚至團(tuán)隊(duì)都不一樣，為了便于溝通，便有了接口文檔。從這里可以看出，接口文檔大多時(shí)候是給開發(fā)看的，那么產(chǎn)品為什么要會(huì)看這玩意呢？

首先，在迭代或依賴其他系統(tǒng)時(shí)，你能明確知道有哪些資源。例如下面這個(gè)關(guān)于微信菜單創(chuàng)建的接口，從這個(gè)接口的參數(shù)“type”的說(shuō)明，我們就能清楚的知道，微信菜單能實(shí)現(xiàn)3種交互：一是直接點(diǎn)擊打開網(wǎng)頁(yè)；二是消息推送；三是跳轉(zhuǎn)小程序。

其次，業(yè)務(wù)很復(fù)雜的時(shí)候可以通過(guò)接口反推，例如我們?cè)谧銎谪浶枨髸r(shí)，不清楚期貨產(chǎn)品分為哪些，這時(shí)我們便可以找到恒生的接口查查它的數(shù)據(jù)字典，結(jié)果就發(fā)現(xiàn)答案竟如此清晰：

再次，在寫需求文檔或和開發(fā)溝通發(fā)現(xiàn)說(shuō)不明白時(shí)，也可以通過(guò)文檔來(lái)澄清。例如做內(nèi)容排序時(shí)可能有多個(gè)時(shí)間：創(chuàng)建時(shí)間、更新時(shí)間、操作時(shí)間等等。而你想調(diào)用的時(shí)間和開發(fā)理解的可能會(huì)存在差異，這時(shí)你便可拉出接口文檔告訴他我要的就是CreateTime。

當(dāng)然啦，接口文檔還有很多妙用，比如作為撕逼利器、裝逼神器等等，歡迎大家在留言區(qū)寫下你的文檔故事~

三、接口文檔怎么看？

接口文檔有這么多好處，那我們?cè)趺慈プx懂它呢？在這里我們用微信訂閱通知的接口文檔作為學(xué)習(xí)材料。

如上圖所示，接口通常分為四部分：請(qǐng)求方法、url、請(qǐng)求參數(shù)、返回參數(shù)：

1）請(qǐng)求方法：常用的方法就是下面的四種——GET、PUT、POST、DELETE。

• GET請(qǐng)求會(huì)向數(shù)據(jù)庫(kù)發(fā)索取數(shù)據(jù)的請(qǐng)求，從而來(lái)獲取信息。該請(qǐng)求就像數(shù)據(jù)庫(kù)的select操作一樣，只是用來(lái)查詢一下數(shù)據(jù)，不會(huì)修改、增加數(shù)據(jù)，不會(huì)影響資源的內(nèi)容，即該請(qǐng)求不會(huì)產(chǎn)生副作用。
• 與GET不同的是，PUT請(qǐng)求是向服務(wù)器端發(fā)送數(shù)據(jù)的，從而改變信息。該請(qǐng)求就像數(shù)據(jù)庫(kù)的update操作一樣，用來(lái)修改數(shù)據(jù)的內(nèi)容，但是不會(huì)增加數(shù)據(jù)的種類等。
• POST請(qǐng)求同PUT請(qǐng)求類似，都是向服務(wù)器端發(fā)送數(shù)據(jù)的，但是該請(qǐng)求會(huì)改變數(shù)據(jù)的種類等資源，就像數(shù)據(jù)庫(kù)的insert操作一樣，會(huì)創(chuàng)建新的內(nèi)容。目前所有的提交操作幾乎都是用POST請(qǐng)求。
• DELETE請(qǐng)求顧名思義，就是用來(lái)刪除某一個(gè)資源的，該請(qǐng)求就像數(shù)據(jù)庫(kù)的delete操作。

這個(gè)概念產(chǎn)品經(jīng)理簡(jiǎn)單了解即可，一般不考

2）url：以微信微信訂閱通知接口的url為例

我們可以把這個(gè) URL 分解成 5部分：

• 協(xié)議部分：指訪問(wèn)服務(wù)器獲取資源時(shí)，需要使用哪種協(xié)議。常用的有http、https、ftp協(xié)議等。本例中的為https。
• 域名部分：指資源宿主服務(wù)器的主機(jī)名或IP地址。本例中的域名部分為：a。URL中也可以使用IP作為域名。
• 端口部分：域名和端口之間使用“:“作為分隔符，端口不是一個(gè)URL必須的部分。http服務(wù)的默認(rèn)端口是80，這種情況下端口號(hào)可以省略，如果使用了其他端口必須知名，例如：。
• 虛擬目錄部分：該部分說(shuō)明了資源位于服務(wù)器的什么地方。從域名后的第一個(gè)“/“開始到最后一個(gè)“/“為止，是虛擬目錄部分。本例中的虛擬目錄是“/wxaapi/newtmpl/”。
• 文件名部分：從域名的最后一個(gè)”/“開始到”?“為止，是文件名部分。如果沒(méi)有”?“，則是從域名后的最后一個(gè)“/”開始到“#”為止；如果沒(méi)有“？”和“#”，那么從域名后的最后一個(gè)“/”開始到結(jié)束，都是文件名部分。文件名部分也不是一個(gè)URL必須的部分，如果省略該部分，則使用默認(rèn)的文件名。本例中的文件名是“addtemplate”。

同樣，產(chǎn)品經(jīng)理不需要非常明白。

3）請(qǐng)求參數(shù)和返回參數(shù)：請(qǐng)求參數(shù)和返回參數(shù)都分為：字段、說(shuō)明、類型、默認(rèn)值、是否必填這5列。

字段：類的屬性

說(shuō)明：中文釋義

類型：屬性的類型，只有String、Number、Object、Array四大類

備注：一些解釋語(yǔ)，或者寫簡(jiǎn)單的示例

4）返回參數(shù)，要分兩種情況討論：

只返回接口調(diào)用成功或者失敗：code、reason

返回參數(shù)：字段、說(shuō)明、類型、默認(rèn)值、是否必填

四、一些可供學(xué)習(xí)的網(wǎng)址

微信開放文檔

金融交易統(tǒng)一接入平臺(tái)

高德地圖API

作者：阿宅的產(chǎn)品筆記；公眾號(hào)：阿宅的產(chǎn)品筆記（PMZZnote）

本文由 @公眾號(hào)阿宅的產(chǎn)品筆記 原創(chuàng)發(fā)布于人人都是產(chǎn)品經(jīng)理。未經(jīng)許可，禁止轉(zhuǎn)載

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