產品後臺怎麼操作（接口文檔怎麼用）

2023-04-16 00:47:51 2

編輯導讀：為了方便開發和產品溝通，便有了接口文檔。接口文檔大多時候是給開發看的，那麼產品為什麼要會看接口文檔呢？本文作者對此發表了自己的看法，一起來看看吧。

又到了周末，快樂開黑開始！阿宅興衝衝得找小夥伴上號，結果小夥伴爾康擺手：「等一下，我先開電腦噴下開發。」

阿宅一局酣戰之後，又來找到小夥伴：「好了沒？」「沒好，我被開發噴了，是我的需求bug，老闆還罵我了，你看。」

為了讓小夥伴儘快上號，我們開始一起復盤：「這是關於基金購買流程的需求，我在這個地方需要先明確基金的委託類型，我問爺爺找爸爸終於把這個理清楚了，可以分為購買、贖回、定投。結果上線後才發現分類沒定義完整。」「這玩意不是接口裡寫得明明白白嗎？」

「！！！！接口文檔是個啥！我怎麼從來沒看過！」

「你啊你，都做了半年理財產品了，竟然連這個都不知道。那本宅就大發慈悲教教你吧，記住明天給我一根冰糖葫蘆。」

一、什麼是接口文檔？

首先，什麼是接口？你可以把它簡單理解為一個函數，你輸入x，它就會告訴你y。你無需知道這個函數的邏輯，只需要知道輸入什麼樣的問題，會得到什麼樣的答案就可以了。

但x怎麼輸，會出現什麼樣的y，就需要通過接口文檔來了解。就比如下圖的表格，當你按照「輸入參數」輸入「委託方式」、「分支機構」等參數時，這個接口就會告訴你「資產帳戶」是什麼。

恒生統一接入平臺_周邊接口規範(期貨,期權_20210812).xls

二、產品為什麼要能看懂接口文檔？

接口一般來講分為兩種：

程序內部的接口：方法與方法、模塊與模塊之間的交互，如登錄發帖，發帖就必須要登錄，如果不登錄不能發帖，發帖和登錄這兩個模塊之間就要有交互，就會拋出一個接口，進行內部系統調用。系統對外的接口：從別人的網站或伺服器上獲取資源或信息，對方不會提供資料庫，只能提供一個寫好的方法來獲取數據，如購物網站和第三方支付，購物網站支付時可選擇第三方支付方法，但第三方不會提供自己的資料庫給購物網站，只會提供一個接口，供購物網站進行調用。

這便意味著開發的人甚至團隊都不一樣，為了便於溝通，便有了接口文檔。從這裡可以看出，接口文檔大多時候是給開發看的，那麼產品為什麼要會看這玩意呢？

首先，在迭代或依賴其他系統時，你能明確知道有哪些資源。例如下面這個關於微信菜單創建的接口，從這個接口的參數「type」的說明，我們就能清楚的知道，微信菜單能實現3種交互：一是直接點擊打開網頁；二是消息推送；三是跳轉小程序。

其次，業務很複雜的時候可以通過接口反推，例如我們在做期貨需求時，不清楚期貨產品分為哪些，這時我們便可以找到恒生的接口查查它的數據字典，結果就發現答案竟如此清晰：

再次，在寫需求文檔或和開發溝通發現說不明白時，也可以通過文檔來澄清。例如做內容排序時可能有多個時間：創建時間、更新時間、操作時間等等。而你想調用的時間和開發理解的可能會存在差異，這時你便可拉出接口文檔告訴他我要的就是CreateTime。

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

三、接口文檔怎麼看？

接口文檔有這麼多好處，那我們怎麼去讀懂它呢？在這裡我們用微信訂閱通知的接口文檔作為學習材料。

如上圖所示，接口通常分為四部分：請求方法、url、請求參數、返回參數：

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

GET請求會向資料庫發索取數據的請求，從而來獲取信息。該請求就像資料庫的select操作一樣，只是用來查詢一下數據，不會修改、增加數據，不會影響資源的內容，即該請求不會產生副作用。與GET不同的是，PUT請求是向伺服器端發送數據的，從而改變信息。該請求就像資料庫的update操作一樣，用來修改數據的內容，但是不會增加數據的種類等。POST請求同PUT請求類似，都是向伺服器端發送數據的，但是該請求會改變數據的種類等資源，就像資料庫的insert操作一樣，會創建新的內容。目前所有的提交操作幾乎都是用POST請求。DELETE請求顧名思義，就是用來刪除某一個資源的，該請求就像資料庫的delete操作。

這個概念產品經理簡單了解即可，一般不考

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

我們可以把這個 URL 分解成 5部分：

協議部分：指訪問伺服器獲取資源時，需要使用哪種協議。常用的有http、https、ftp協議等。本例中的為https。域名部分：指資源宿主伺服器的主機名或IP位址。本例中的域名部分為：api.weixin.qq.com。URL中也可以使用IP作為域名。埠部分：域名和埠之間使用「:「作為分隔符，埠不是一個URL必須的部分。http服務的默認埠是80，這種情況下埠號可以省略，如果使用了其他埠必須知名，例如：http://www.azhai.com:90/。虛擬目錄部分：該部分說明了資源位於伺服器的什麼地方。從域名後的第一個「/「開始到最後一個「/「為止，是虛擬目錄部分。本例中的虛擬目錄是「/wxaapi/newtmpl/」。文件名部分：從域名的最後一個」/「開始到」?「為止，是文件名部分。如果沒有」?「，則是從域名後的最後一個「/」開始到「#」為止；如果沒有「？」和「#」，那麼從域名後的最後一個「/」開始到結束，都是文件名部分。文件名部分也不是一個URL必須的部分，如果省略該部分，則使用默認的文件名。本例中的文件名是「addtemplate」。

同樣，產品經理不需要非常明白。

3）請求參數和返回參數：請求參數和返回參數都分為：欄位、說明、類型、默認值、是否必填這5列。

欄位：類的屬性

說明：中文釋義

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

備註：一些解釋語，或者寫簡單的示例

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

只返回接口調用成功或者失敗：code、reason

返回參數：欄位、說明、類型、默認值、是否必填

四、一些可供學習的網址

微信開放文檔

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

金融交易統一接入平臺

https://ufx.hs.net/

高德地圖API

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

作者：阿宅的產品筆記；公眾號：阿宅的產品筆記（PMZZnote）

本文由 @公眾號阿宅的產品筆記 原創發布於人人都是產品經理。未經許可，禁止轉載

題圖來自Unsplash，基於CC0協議

,