高效地重建API文檔
當(dāng)你接手一個缺乏管理的項目時，項目的API可能已開發(fā)完成，但卻由于沒有API文檔，使得維護工作變得異常艱難。
通過Postman的內(nèi)置proxy(代理)和interceptor(攔截器)，我們可以快速地為現(xiàn)有項目在Postman中重建API文檔。
重建API文檔分為2個部分：首先我們需要通過Postman的內(nèi)置代理或者攔截器捕獲所有請求，之后再為這些請求添加必要的內(nèi)容來完善API文檔。
捕獲請求
使用內(nèi)置代理捕獲請求
通過Postman的內(nèi)置代理來捕獲請求，需要執(zhí)行以下步驟：
1.首先確保目標(biāo)設(shè)備與運行Postman的計算機處于同一網(wǎng)絡(luò)，之后設(shè)置代理端口，并將Capture Requests選項切換為啟用。
?(代理設(shè)置)?
2.然后為目標(biāo)設(shè)備設(shè)置網(wǎng)絡(luò)代理，代理服務(wù)器需要填寫運行Postman的計算機的IP地址，之后只要目標(biāo)設(shè)備發(fā)起了網(wǎng)絡(luò)請求，我們便能在Postman中查看并保存這些請求。
??(代理設(shè)置)?
?(捕獲的請求)?
使用攔截器捕獲請求
使用Postman的攔截器需要安裝對應(yīng)的Chrome擴展：Postman Interceptor。
(Postman Interceptor)?
安裝后之后，點擊Postman Interceptor擴展的圖標(biāo)，在設(shè)置頁面將Capture Requests選項設(shè)置為啟用即可。當(dāng)其狀態(tài)顯示為CONNECTED，則表明攔截器正在工作中。
?(工作中的攔截器)?
完善API文檔
為了排除無用的請求，我們可以通過設(shè)置Host(主機)來捕獲特定的請求，或者在捕獲請求后使用過濾器來對請求進行篩選。
之后，我們在Postman中重新發(fā)起這些請求，并為其添加描述信息、參數(shù)說明、響應(yīng)示例等，如此便能快速在Postman中重建API文檔。
??(捕獲的請求示例)??
內(nèi)置代理與攔截器的不足
Postman的內(nèi)置代理并不能捕獲Https，并且內(nèi)置代理與攔截器在工作過程中都會獲取到大量無用請求，例如圖片、CSS等靜態(tài)資源，因此并不能替代Charles這類Web調(diào)試代理工具。相反，將兩者配合使用，各取所長，方能事半功倍。
高效地維護API
我們可以利用Postman提供的變量與環(huán)境來高效的維護API。
首先，我們按照?Martin Fowler在《重構(gòu):改善既有代碼的設(shè)計》提出的“事不過三，三則重構(gòu)”的原則，對現(xiàn)在的API進行優(yōu)化。
例如，對于“添加角色”與“編輯角色”這2個API。
?(API：添加角色)??
??(API：編輯角色)??
首先，它們的URL中，協(xié)議(Http)、主機(www.app.com)、端口(80)、及部分路徑(api)均相同，即存在相同的URL內(nèi)容。
其次，它們的Header的內(nèi)容完全相同，而且其中Authorization的值會經(jīng)常發(fā)生變化。
最后，通常我們都會部署開發(fā)、測試、生產(chǎn)等幾個環(huán)境，但當(dāng)前的API中我們并不能區(qū)分出這幾個環(huán)境，因此需要使得其可適應(yīng)不同場景。
為此，我們通過Postman的變量與環(huán)境來解決這個問題。
變量與環(huán)境
Postman中的變量與編程語言中的變量并無差別，都是數(shù)據(jù)的符號表示，并且通過符號可以訪問其對應(yīng)的值。
環(huán)境是變量的集合，即是一個環(huán)境中包含了多個變量。
這個問題中，首先我們創(chuàng)建一個develop環(huán)境用于開發(fā)，并在其中創(chuàng)建Base_Url、Host、Content-Type、Accept、AccessToken等變量。
?(develop環(huán)境中的變量)??
之后，我們復(fù)制develop的副本為test與product，并更改對應(yīng)環(huán)境BaseUrl變量的值，這樣我們便可以通過切換環(huán)境來向不同的服務(wù)器發(fā)送請求。
最終創(chuàng)建的環(huán)境如下：
接著，我們再對之前的API進行修改，把API中重復(fù)的部分用變量進行替換(Postman中變量的使用方式為{{變量名}})。
????(修改后的API：添加角色)
???(修改后的API：編輯角色)
如此一來，我們既能通過變量方便對管理API中經(jīng)常變化的部分，又能通過環(huán)境在開發(fā)、測試等工作中自由切換。
關(guān)于變量的更多細節(jié)
Postman中變量共分為全局變量、集合變量、環(huán)境變量、數(shù)據(jù)變量、本地變量5種，它們的優(yōu)先級由低到高遞增，但生命周期卻是由高到低遞減。
??(Postman中的變量類型，引用自Postman官網(wǎng))
全局變量
全局變量在整個工作區(qū)有效，我們可以通過點擊Manage enviroments窗口的Globals按鈕進入全局變量的管理界面。
?(全局變量的操作入口)
集合變量
集合變量只在特定的集合內(nèi)有效，因此Postman中集合變量的操作入口并不明顯，首先需要點擊集合右側(cè)的更多按鈕，在彈出的菜單項中選擇Edit，進入集合變量編輯界面。
??(集合變量的操作入口)
然后切換到Variables選項卡，即可對集合變量進行管理。
???(集合變量的編輯界面)
環(huán)境變量
只有當(dāng)環(huán)境被啟用時，對應(yīng)的環(huán)境變量才會生效。我們可以在Postman的右上角切換當(dāng)前環(huán)境。
??(切換環(huán)境)
然后在Manage enviroments窗口中點擊具體的環(huán)境名并進入環(huán)境變量的管理界面。
??(環(huán)境變量的操作入口)
數(shù)據(jù)變量
數(shù)據(jù)變量的使用涉及到Runner與Sandbox，暫且不表。
本地變量
本地變量是臨時的，只能在請求腳本中訪問，并且在請求完成后就被自動刪除。
由于本地變量的使用涉及到Pre-request Script(預(yù)請求腳本)與Sandbox(沙盒)，此處亦暫且不表。
動態(tài)變量
動態(tài)變量是按照變量的值劃分的，普通變量的值是固定的，只有在我們手動更改其值才會發(fā)生變化(可在編輯窗口或者Sandbox中使用腳本更改)，而動態(tài)變量的值則是每次使用時發(fā)生改變，且是由Postman動態(tài)生成。
Postman內(nèi)置的動態(tài)變量非常多，包含了數(shù)值、顏色、IP地址、電話、地址、坐標(biāo)等眾多種類，這些動態(tài)變量的名稱大多以$random開頭，具體的動態(tài)變量列表可以參考官方文檔。
高效地測試API
Postman為我們提供了豐富的測試功能，我們可以很方便地利用Tests與Runner來實現(xiàn)自動化測試。以“用戶-注冊”這個API為例：
首先，我們用動態(tài)變量代替固定的用戶名和郵箱，以此來模擬用戶的注冊操作。
?(包含動態(tài)變量的API：注冊)
然后，我們在Tests選項卡中用JavaScript編寫測試腳本。在編寫測試腳本時，我們既可以點擊右側(cè)的Snippets示例獲取代碼，也可以參考Postman的官方文檔。
???(JavaScript編寫的測試腳本)
在接收到響應(yīng)報文后，Postman會自動在Sandbox中運行對應(yīng)的測試腳本，并給出測試結(jié)果。
?????(API的測試結(jié)果)
Runner
當(dāng)我們需要自動化的對整個集合的API進行測試時，就需要使用到Runner。
Runner會自動運行集合中的所有API，并可以指定API的環(huán)境、迭代次數(shù)以及運行每個API的等待間隔，之后Runner將會依次執(zhí)行這些API，并給出運行結(jié)果報告。
??(Runner配置界面)
?(運行結(jié)果報告)
下一篇《Postman(第3期)：協(xié)作》，敬請期待。
