編輯導(dǎo)讀：為了方便開發(fā)和產(chǎn)品溝通，便有了接口文檔。接口文檔大多時(shí)候是給開發(fā)看的，那么產(chǎn)品為什么要會(huì)看接口文檔呢？本文作者對(duì)此發(fā)表了自己的看法，一起來看看吧。

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

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

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

“！?。?！接口文檔是個(gè)啥！我怎么從來沒看過！”

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

一、什么是接口文檔？

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

但x怎么輸，會(huì)出現(xiàn)什么樣的y，就需要通過接口文檔來了解。就比如下圖的表格，當(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)品為什么要能看懂接口文檔？

接口一般來講分為兩種：

• 程序內(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ù)庫，只能提供一個(gè)寫好的方法來獲取數(shù)據(jù)，如購物網(wǎng)站和第三方支付，購物網(wǎng)站支付時(shí)可選擇第三方支付方法，但第三方不會(huì)提供自己的數(shù)據(jù)庫給購物網(wǎng)站，只會(huì)提供一個(gè)接口，供購物網(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”的說明，我們就能清楚的知道，微信菜單能實(shí)現(xiàn)3種交互：一是直接點(diǎn)擊打開網(wǎng)頁；二是消息推送；三是跳轉(zhuǎn)小程序。

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

再次，在寫需求文檔或和開發(fā)溝通發(fā)現(xiàn)說不明白時(shí)，也可以通過文檔來澄清。例如做內(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ù)庫發(fā)索取數(shù)據(jù)的請(qǐng)求，從而來獲取信息。該請(qǐng)求就像數(shù)據(jù)庫的select操作一樣，只是用來查詢一下數(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ù)庫的update操作一樣，用來修改數(shù)據(jù)的內(nèi)容，但是不會(huì)增加數(shù)據(jù)的種類等。
• POST請(qǐng)求同PUT請(qǐng)求類似，都是向服務(wù)器端發(fā)送數(shù)據(jù)的，但是該請(qǐng)求會(huì)改變數(shù)據(jù)的種類等資源，就像數(shù)據(jù)庫的insert操作一樣，會(huì)創(chuàng)建新的內(nèi)容。目前所有的提交操作幾乎都是用POST請(qǐng)求。
• DELETE請(qǐng)求顧名思義，就是用來刪除某一個(gè)資源的，該請(qǐng)求就像數(shù)據(jù)庫的delete操作。

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

2）url：以微信微信訂閱通知接口的url為例https://api.weixin.qq.com/wxaapi/newtmpl/addtemplate?access_token=ACCESS_TOKEN

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

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

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

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

字段：類的屬性

說明：中文釋義

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

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

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

只返回接口調(diào)用成功或者失?。篶ode、reason

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

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

微信開放文檔

https://developers.weixin.qq.com/doc/offiaccount/Subscription_Messages/api.html

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

https://ufx.hs.net/

高德地圖API

http://lbs.amap.com/api/jsapi-v2/summary

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

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

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