Postman 是一個介面測試和 http 請求的神器，非常好用。

Postman 的優點：

• 支援各種的請求型別: get、post、put、patch、delete 等
• 支援線上儲存資料，通過賬號就可以進行遷移資料
• 很方便的支援請求 header 和請求引數的設定
• 支援不同的認證機制，包括 Basic Auth，Digest Auth，OAuth 1.0，OAuth 2.0 等
• 響應資料是自動按照語法格式高亮的，包括 HTML，JSON 和 XML

安裝

Postman 可以單獨作為一個應用安裝，也可以作為 chrome 的一個外掛安裝。

下面主要介紹下載安裝獨立版本app 軟體的 Postman 的過程：

去下載自己平臺的版本：

• Mac
• Windows（x86/x64）
• Linux（x86/x64） 即可。

安裝成功後，開啟軟體。

新建介面

對應的Request：New -> Request

或，在右邊的 Tab 頁面中點選加號+：

即可看到新建的 Tab 頁：

設定 HTTP 的 Method 方法和輸入 api 的地址

傳送請求

都填寫好之後，點選 Send 去傳送請求 Request：

然後可以重複上述修改 Request 的引數，點選 Send 去傳送請求的過程，以便除錯到 API 介面正常工作為止。

待整個介面都除錯完畢後，記得點選 Save 去儲存介面資訊：

去儲存當前 API 介面，然後需要填寫相關的介面資訊：

• Request Name: 請求的名字
  • 我一般習慣用儲存為 介面的最後的欄位名，比如http://{% raw %}{{% endraw %}{server_address}}/ucows/login/login中的/login/login
• Request Description: 介面的描述
  • 可選 最好寫上該介面的要實現的基本功能和相關注意事項
  • 支援 Markdown 語法
• Select a collection or folder to save: 選擇要儲存到哪個分組（或資料夾）
  • 往往儲存到某個 API 介面到所屬的該專案名的分組

填寫好內容，選擇好分組，再點選儲存：

此時，Tab 的右上角的黃色點（表示沒有儲存）消失了，表示已儲存。

且對應的分組中可以看到對應的介面了：

[warning] 預設不儲存返回的 Response 資料

• 直接點選 Save 去儲存，只能儲存 API 本身（的 Request 請求），不會儲存 Response 的資料
• 想要儲存 Response 資料，需要用後面要介紹的 多個 Example

比如，對於一個 GET 的請求的 url 是： http://openapi.youdao.com/api?q=糾刪碼(EC)的學習&from=zh_CHS&to=EN&appKey=152e0e77723a0026&salt=4&sign=6BE15F1868019AD71C442E6399DB1FE4

對應著其實是?key=value形式中包含多個 Http 的 GET 的 query string=query parameters

Postman 可以自動幫我們解析出對應引數，可以點選 Params：

看到展開的多個引數：

如此就可以很方便的修改，增刪對應的引數了。

且還支援，在不刪除某引數的情況下，如果想要暫時不傳引數，可以方便的通過不勾選的方式去實現：

當然，如果想要批量的編輯引數，可以點選右上角的Bulk Edit，去實現批量編輯。

所以，可以很方便的新增有條理的介面描述，尤其是引數解釋了：

而對於要解釋的引數，可以通過之前的Param -> Bulk Edit的內容：

拷貝過來，再繼續去編輯：

以及新增更多解釋資訊：

點選 Update 後，即可儲存。

去釋出後：

對應的效果：有道翻譯

Postman 對於返回的 Response 資料，支援三種顯示模式。

• 預設格式化後的 Pretty 模式

• Raw 原始模式

點選Raw，可以檢視到返回的沒有格式化之前的原始資料：

• Preview 預覽模式

以及 Preview，是對應 Raw 原始格式的預覽模式：

Preview 這種模式的顯示效果，好像是對於返回的是 html 頁面這類，才比較有效果。

很多時候普通的 API 呼叫，倒是沒有 Cookie 的：

舉例，此處返回的是有 Headers 頭資訊的：

可以從中看到伺服器是 Nginx 的。

之前想要實現，讓匯出的 API 文件中能看到介面返回的 Response 資料。後來發現是Example這個功能去實現此效果的。

繼續點選Save Example：

儲存後，就能看到Example(1)了：

然後再去匯出文件，匯出文件中的確能看到返回資料的例子： 

在剛開始一個專案時，為了後續便於組織和管理，把同屬該專案的多個 API，放在一組裡

所以要先去新建一個 Collection: New -> Collection

使用了段時間後，建了多個分組的效果：

單個分組展開後的效果：

Postman 支援 history 歷史記錄，顯示出最近使用過的 API： 

現存問題

在測試 API 期間，往往存在多種環境，對應 IP 地址（或域名也不同）

比如：

• Prod: http://116.62.25.57/ucows
  • 用於開發完成釋出到生產環境
• Dev: http://123.206.191.125/ucows
  • 用於開發期間的線上的 Development 的測試環境
• LocalTest: http://192.168.0.140:80/ucows
  • 用於開發期間配合後臺開發人員的本地區域網內的本地環境，用於聯合除錯 API 介面

而在測試 API 期間，往往需要手動去修改 API 的地址：

效率比較低，且地址更換後之前地址就沒法保留了。

另外，且根據不同 IP 地址（或者域名）也不容易識別是哪套環境。

後來發現 Postman 中，有 Environment 和 Global Variable，用於解決這個問題，實現不同環境的管理：

很明顯，就可以用來實現不用手動修改 url 中的伺服器地址，從而動態的實現，支援不同伺服器環境:

• Production 生產環境
• Development 開發環境
• Local 本地區域網環境

或者：

Environments are a group of variables & values, that allow you to quickly switch the context for your requests and collections.

Learn more about environments

You can declare a variable in an environment and give it a starting value, then use it in a request by putting the variable name within curly-braces. Create an environment to get started.

輸入 Key 和 value：

點選 Add 後：

[info] 環境變數可以使用的地方

• URL
• URL params
• Header values
• form-data/url-encoded values
• Raw body content
• Helper fields
• 寫 test 測試指令碼中
• 通過 postman 的介面，獲取或設定環境變數的值。

此處把之前的在 url 中的 IP 地址（或域名）換成環境變數：

滑鼠移動到環境變數上，可以動態顯示出具體的值：

再去新增另外一個開發環境：

則可新增完 2 個環境變數，表示兩個伺服器地址，兩個版本：

然後就可以切換不同伺服器環境了：

可以看到，同樣的變數 server_address，在切換後對應 IP 地址就變成希望的開發環境的 IP 了：

順帶也去看看，匯出為 API 文件後，帶了這種 Environment 的變數的介面，文件長什麼樣子：

發現是在釋出之前，需要選擇對應的環境的：

釋出後的文件，可以看到所選環境和對應伺服器的 IP 的：

當然釋出文件後，也可以實時切換環境：

當更換伺服器時，直接修改變數的 IP 地址：

即可實時更新，當滑鼠移動到變數上即可看到效果：

對於當前的請求，還可以通過點選 Code

去檢視對應的符合 HTTP 協議的原始的內容：

比如：

• Swift 語言

• Java 語言

• 其他各種語言 還支援其他各種語言：

目前支援的語言有：

• HTTP
• C (LibCurl)
• cURL
• C#(RestSharp)
• Go
• Java
  • OK HTTP
  • Unirest
• Javascript
• NodeJS
• Objective-C(NSURL)
• OCaml(Cohttp)
• PHP
• Python
• Ruby(NET::Http)
• Shell
• Swift(NSURL)

程式碼生成工具的好處是：在寫呼叫此 API 的程式碼時，就可以參考對應程式碼，甚至拷貝貼上對應程式碼，即可。

測試介面

選中某個分組後，點選 Runner

選中某個分組後點擊 Run

即可看到測試結果： 

關於此功能的介紹可參考Postman 官網的git 圖

直接參考官網。

功能介面

Postman 支援多 tab 頁，於此對比之前有些 API 除錯工具就不支援多 Tab 頁，比如Advanced Rest Client

多 tab 的好處：

方便在一個 tab 中測試，得到結果後，複製貼上到另外的 tab 中，繼續測試其它介面

比如此處 tab1 中，測試了獲取驗證碼介面後，拷貝手機號和驗證碼，貼上到 tab2 中，繼續測試註冊的介面

Postman 的預設的 Request 和 Response 是上下佈局：

此處點選右下角的Two pane view，就變成左右的了：

[info] 左右佈局的用途

對於資料量很大，又想要同時看到請求和返回的資料的時候，應該比較有用。

多顏色主題

Posman 支援兩種主題：

• 深色主題

當前是深色主題，效果很不錯：

• 淺色主題

可以切換到 淺色主題：

在服務端後臺的開發人員測試好了介面後，打算把介面的各種資訊發給使用此 API 的前端的移動端人員時，往往會遇到：

要麼是用複製貼上 -> 格式不友好 要麼是用 Postman 中截圖 -> 方便看，但是不方便獲得 API 介面和欄位等文字內容 要麼是用 Postman 中匯出為 JSON -> json 檔案中資訊太繁雜，不利於找到所需要的資訊 要麼是用文件，比如去編寫 Markdown 文件 -> 但後續 API 的變更需要實時同步修改文件，也會很麻煩 這都會導致別人檢視和使用 API 時很不方便。

-> 對此，Postman 提供了釋出 API

預覽和釋出 API 文件 下面介紹 Postman 中如何預覽和釋出 API 文件。

1. Collection
2. 滑鼠移動到某個 Collection，點選 三個點
3. Publish Docs
4. Publish
5. 得到 Public URL
6. 別人開啟這個 Public URL，即可檢視 API 文件

點選分組右邊的大於號>

如果只是預覽，比如後臺開發員自己檢視 API 文件的話，可以選擇：View in web

等價於點選Publish Docs去釋出：

View in Web 後，有 Publish 的選項（見後面的截圖）

View in Web 後，會開啟預覽頁面：

比如：

奶牛雲

https://documenter.getpostman.com/collection/view/669382-42273840-6237-dbae-5455-26b16f45e2b9

而右邊的示例程式碼，也可以從預設的 cURL 換成其他的：

如果想要讓其他人能看到這個文件，則點選 Publish：

然後會開啟類似於這樣的地址：

Postman Documenter

https://documenter.getpostman.com/collection/publish?meta=Y29sbGVjdGlvbl9pZD00MjI3Mzg0MC02MjM3LWRiYWUtNTQ1NS0yNmIxNmY0NWUyYjkmb3duZXI9NjY5MzgyJmNvbGxlY3Rpb25fbmFtZT0lRTUlQTUlQjYlRTclODklOUIlRTQlQkElOTE=

點選 Publish 後，可以生成對應的公開的網頁地址：

開啟 API 介面文件地址：

https://documenter.getpostman.com/view/669382/collection/77fd4RM

即可看到（和前面預覽一樣效果的 API 文件了）：

如此，別人即可檢視對應的 API 介面文件。

後續如果自己的 API 介面修改後：

比如：

（後來發現，不用再去進入此預覽和釋出的流程，去更新文件，而是 Postman 自動支援）

別人去重新整理該文件的頁面：

https://documenter.getpostman.com/view/669382/collection/77fd4RM

即可看到更新後的內容：

參考資料