Postman 接口測試神器

更好的體驗，請直接打開：當前文章。

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

官方 github 地址: https://github.com/postmanlabs

Postman 的優(yōu)點：

• 支持各種的請求類型: get、post、put、patch、delete 等
• 支持在線存儲數(shù)據(jù)，通過賬號就可以進行遷移數(shù)據(jù)
• 很方便的支持請求 header 和請求參數(shù)的設置
• 支持不同的認證機制，包括 Basic Auth，Digest Auth，OAuth 1.0，OAuth 2.0 等
• 響應數(shù)據(jù)是自動按照語法格式高亮的，包括 HTML，JSON 和 XML

以下內(nèi)容主要參考： Github: api_tool_postman

安裝

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

• chrome 插件安裝, Postman 插件地址

• 單獨應用安裝下載

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

去主頁Postman 官網(wǎng)找到：Postman | Apps

安裝

去下載自己平臺的版本：

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

快速入門，總體使用方略

安裝成功后，打開軟件。

新建接口

對應的Request：New -> Request

Postman新建Request

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

Postman在Tab頁新建Request

即可看到新建的 Tab 頁：

Postman新建了的Tab頁的Request

設置 HTTP 請求的方法

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

Postman設置Method和輸入API地址

設置相關請求頭信息

Postman設置Header頭的key

Postman設置Header頭的value

設置相關 GET 或 POST 等的參數(shù)

Postman設置POST的Body的JSON

發(fā)送請求

都填寫好之后，點擊 Send 去發(fā)送請求 Request：

Postman點擊發(fā)送請求

查看響應 Response的信息

Postman返回響應

然后可以重復上述修改 Request 的參數(shù)，點擊 Send 去發(fā)送請求的過程，以便調(diào)試到 API 接口正常工作為止。

保存接口配置

待整個接口都調(diào)試完畢后，記得點擊 Save 去保存接口信息：

Postman點擊Save保存

去保存當前 API 接口，然后需要填寫相關的接口信息：

• Request Name: 請求的名字
  • 我一般習慣用保存為 接口的最后的字段名，比如http://{% raw %}{{% endraw %}{server_address}}/ucows/login/login中的/login/login
• Request Description: 接口的描述
  • 可選 最好寫上該接口的要實現(xiàn)的基本功能和相關注意事項
  • 支持 Markdown 語法
• Select a collection or folder to save: 選擇要保存到哪個分組（或文件夾）
  • 往往保存到某個 API 接口到所屬的該項目名的分組

Postman保存時填寫接口信息

填寫好內(nèi)容，選擇好分組，再點擊保存：

Postman保存到分組

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

且對應的分組中可以看到對應的接口了：

Postman已保存的API接口Tab頁

[warning] 默認不保存返回的 Response 數(shù)據(jù)

• 直接點擊 Save 去保存，只能保存 API 本身（的 Request 請求），不會保存 Response 的數(shù)據(jù)
• 想要保存 Response 數(shù)據(jù)，需要用后面要介紹的 多個 Example

Request 的多參數(shù)操作詳解

自動解析多個參數(shù) Params

比如，對于一個 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 可以自動幫我們解析出對應參數(shù)，可以點擊 Params：

Postman中GET時多個參數(shù)

看到展開的多個參數(shù)：

Postman中GET中展開的多個參數(shù)

如此就可以很方便的修改，增刪對應的參數(shù)了。

臨時禁用參數(shù)

且還支持，在不刪除某參數(shù)的情況下，如果想要暫時不傳參數(shù)，可以方便的通過不勾選的方式去實現(xiàn)：

Postman中不勾選個別參數(shù)

批量編輯 GET 的多個參數(shù)

當然，如果想要批量的編輯參數(shù)，可以點擊右上角的Bulk Edit，去實現(xiàn)批量編輯。

Postman批量編輯GET參數(shù)

接口描述與自動生成文檔

API 的描述中，也支持 Markdown，官方的接口說明文檔：Intro to API documentation。

所以，可以很方便的添加有條理的接口描述，尤其是參數(shù)解釋了：

Postman給Edit編輯

描述支持 markdown 語法

Postman支持Markdown寫描述

而對于要解釋的參數(shù)，可以通過之前的Param -> Bulk Edit的內(nèi)容：

Postman批量更新參數(shù)

拷貝過來，再繼續(xù)去編輯：

Postman編輯Markdown描述內(nèi)容

以及添加更多解釋信息：

Postman添加更多的Markdown內(nèi)容

點擊 Update 后，即可保存。

發(fā)布接口并生成 markdown 的描述文件

去發(fā)布后：

Postman去Publish Docs

對應的效果：有道翻譯

Postman發(fā)布后Markdown效果

Postman發(fā)布后Markdown中代碼效果

Response 深入

Response 數(shù)據(jù)顯示模式

Postman 對于返回的 Response 數(shù)據(jù)，支持三種顯示模式。

• 默認格式化后的 Pretty 模式

[圖片上傳中...(image-aba4c8-1528862174531-66)]

• Raw 原始模式

點擊Raw，可以查看到返回的沒有格式化之前的原始數(shù)據(jù)：

Postman的Response的Raw模式

• Preview 預覽模式

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

Postman的Response的Preview模式

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

Response 的 Cookies

很多時候普通的 API 調(diào)用，倒是沒有 Cookie 的：

Postman的響應中無Cookie

Response 的 Headers 頭信息

舉例，此處返回的是有 Headers 頭信息的：

Postman的響應中的Headers

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

保存多個 Example

之前想要實現(xiàn)，讓導出的 API 文檔中能看到接口返回的 Response 數(shù)據(jù)。后來發(fā)現(xiàn)是Example這個功能去實現(xiàn)此效果的。

如何添加 Example

Postman的接口點擊Add Example

繼續(xù)點擊Save Example：

Postman的接口點擊Save Example

保存后，就能看到Example(1)了：

Postman已保存的Example(1)

單個 Example 在導出的 API 文檔中的效果

Postman導出API文檔中帶Example

多個 Example 在導出的 API 文檔中的效果

Postman中多個Example在API文檔中效果1

Postman中多個Example在API文檔中效果2

其他好用的功能及工具

分組 Collection

在剛開始一個項目時，為了后續(xù)便于組織和管理，把同屬該項目的多個 API，放在一組里

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

Postman新建分組Colection

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

Postman中的多個分組效果

單個分組展開后的效果：

Postman分組展開的效果

歷史記錄 History

Postman的History顯示歷史記錄

用環(huán)境變量實現(xiàn)多服務器版本

現(xiàn)存問題

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

比如：

• Prod: http://116.62.25.57/ucows
  • 用于開發(fā)完成發(fā)布到生產(chǎn)環(huán)境
• Dev: http://123.206.191.125/ucows
  • 用于開發(fā)期間的線上的 Development 的測試環(huán)境
• LocalTest: http://192.168.0.140:80/ucows
  • 用于開發(fā)期間配合后臺開發(fā)人員的本地局域網(wǎng)內(nèi)的本地環(huán)境，用于聯(lián)合調(diào)試 API 接口

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

Postman修改APi接口中服務器地址

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

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

Postman 支持用 Environment 環(huán)境變量去實現(xiàn)多服務器版本

后來發(fā)現(xiàn) Postman 中，有 Environment 和 Global Variable，用于解決這個問題，實現(xiàn)不同環(huán)境的管理：

Postman中Environment和Globals

很明顯，就可以用來實現(xiàn)不用手動修改 url 中的服務器地址，從而動態(tài)的實現(xiàn)，支持不同服務器環(huán)境:

• Production 生產(chǎn)環(huán)境
• Development 開發(fā)環(huán)境
• Local 本地局域網(wǎng)環(huán)境

如何使用 Enviroment 實現(xiàn)多服務器版本

Postman中點擊??的Add

或者：

Postman中點擊設置Manage Enviroments

Postman中Manage Enviroments的Add

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：

Postman中Enviroment輸入key和value

點擊 Add 后：

Postman保存Enviroment

[info] 環(huán)境變量可以使用的地方

• URL
• URL params
• Header values
• form-data/url-encoded values
• Raw body content
• Helper fields
• 寫 test 測試腳本中
• 通過 postman 的接口，獲取或設置環(huán)境變量的值。

此處把之前的在 url 中的 IP 地址（或域名）換成環(huán)境變量：

Postman把IP換成環(huán)境變量

鼠標移動到環(huán)境變量上，可以動態(tài)顯示出具體的值：

Postman環(huán)境變量鼠標動態(tài)提示

再去添加另外一個開發(fā)環(huán)境：

Postman添加Dev環(huán)境變量

則可添加完 2 個環(huán)境變量，表示兩個服務器地址，兩個版本：

Postman已添加2個環(huán)境變量

然后就可以切換不同服務器環(huán)境了：

Postman切換不同服務器環(huán)境

可以看到，同樣的變量 server_address，在切換后對應 IP 地址就變成希望的開發(fā)環(huán)境的 IP 了：

Postman切換到Dev的IP地址

Postman 導出 API 文檔中多個環(huán)境變量的效果

順帶也去看看，導出為 API 文檔后，帶了這種 Environment 的變量的接口，文檔長什么樣子：

發(fā)現(xiàn)是在發(fā)布之前，需要選擇對應的環(huán)境的：

Postman發(fā)布前要選擇環(huán)境

Postman選擇某個環(huán)境

Postman已選擇了某個環(huán)境

發(fā)布后的文檔，可以看到所選環(huán)境和對應服務器的 IP 的：

Postman發(fā)布后看到所選環(huán)境的IP

當然發(fā)布文檔后，也可以實時切換環(huán)境：

Postman發(fā)布后可以切換環(huán)境

Postman切換到某個環(huán)境看到IP

環(huán)境變量的好處

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

Postman環(huán)境變量要更換IP地址

Postman環(huán)境變量更換為新IP

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

Postman鼠標移動到環(huán)境變量顯示新IP

代碼生成工具

查看當前請求的 HTTP 原始內(nèi)容

對于當前的請求，還可以通過點擊 Code

Postman中點擊Code

去查看對應的符合 HTTP 協(xié)議的原始的內(nèi)容：

Postman查看請求的Http的原始內(nèi)容

各種語言的示例代碼Code Generation Tools

比如：

• Swift 語言

Postman把請求生成Swift代碼

• Java 語言

Postman把請求生成Java代碼

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

Postman把請求生成其他各種語言的代碼

目前支持的語言有：

• 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)

代碼生成工具的好處是：在寫調(diào)用此 API 的代碼時，就可以參考對應代碼，甚至拷貝粘貼對應代碼，即可。

測試接口

選中某個分組后，點擊 Runner

Postman中點擊Runner

選中某個分組后點擊 Run

Postman中點擊Run去測試

Postman中測試API的結(jié)果

關于此功能的介紹可參考Postman 官網(wǎng)的git 圖

MockServer

直接參考官網(wǎng)。

功能界面

多 Tab 分頁

Postman 支持多 tab 頁，于此對比之前有些 API 調(diào)試工具就不支持多 Tab 頁，比如Advanced Rest Client

多 tab 的好處：

方便在一個 tab 中測試，得到結(jié)果后，復制粘貼到另外的 tab 中，繼續(xù)測試其它接口

比如此處 tab1 中，測試了獲取驗證碼接口后，拷貝手機號和驗證碼，粘貼到 tab2 中，繼續(xù)測試注冊的接口

Postman拷貝Tab1中驗證碼

Postman粘貼驗證碼到Tab2

界面查看模式

Postman 的默認的 Request 和 Response 是上下布局：

Postman默認是上下布局

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

Postman換成左右布局

[info] 左右布局的用途

對于數(shù)據(jù)量很大，又想要同時看到請求和返回的數(shù)據(jù)的時候，應該比較有用。

多顏色主題

Posman 支持兩種主題：

• 深色主題

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

Postman的設置深色主題

Postman的深色主題的效果

• 淺色主題

可以切換到 淺色主題：

Postman切換淺色主題

Postman淺色主題效果

API 文檔生成

在服務端后臺的開發(fā)人員測試好了接口后，打算把接口的各種信息發(fā)給使用此 API 的前端的移動端人員時，往往會遇到：

要么是用復制粘貼 -> 格式不友好 要么是用 Postman 中截圖 -> 方便看，但是不方便獲得 API 接口和字段等文字內(nèi)容 要么是用 Postman 中導出為 JSON -> json 文件中信息太繁雜，不利于找到所需要的信息 要么是用文檔，比如去編寫 Markdown 文檔 -> 但后續(xù) API 的變更需要實時同步修改文檔，也會很麻煩 這都會導致別人查看和使用 API 時很不方便。

-> 對此，Postman 提供了發(fā)布 API

預覽和發(fā)布 API 文檔 下面介紹 Postman 中如何預覽和發(fā)布 API 文檔。

簡要概述步驟

1. Collection
2. 鼠標移動到某個 Collection，點擊 三個點
3. Publish Docs
4. Publish
5. 得到 Public URL
6. 別人打開這個 Public URL，即可查看 API 文檔

預覽 API 文檔

點擊分組右邊的大于號>

Postman的分組右邊的>

如果只是預覽，比如后臺開發(fā)員自己查看 API 文檔的話，可以選擇：View in web

Postman的分組的View in web

等價于點擊Publish Docs去發(fā)布：

Postman的分組點擊Publish Docs

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

View in Web 后，會打開預覽頁面：

比如：

奶牛云

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

Postman的API文檔預覽-1

Postman的API文檔預覽-2

而右邊的示例代碼，也可以從默認的 cURL 換成其他的：

示例代碼從cURL換成Python

API文檔中Python示例代碼

發(fā)布 API 文檔

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

API文檔中點擊Publish去發(fā)布

然后會打開類似于這樣的地址：

Postman Documenter

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

Postman確認發(fā)布分組的API文檔

點擊 Publish 后，可以生成對應的公開的網(wǎng)頁地址：

Postman已發(fā)布文檔得到公開鏈接

打開 API 接口文檔地址：

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

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

Postman已發(fā)布的API文檔效果

如此，別人即可查看對應的 API 接口文檔。

已發(fā)布的 API 文檔支持自動更新

后續(xù)如果自己的 API 接口修改后：

比如：

Postman去Edit編輯API

Postman的API更新編輯Edit Request

（后來發(fā)現(xiàn)，不用再去進入此預覽和發(fā)布的流程，去更新文檔，而是 Postman 自動支持）

別人去刷新該文檔的頁面：

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

即可看到更新后的內(nèi)容：

Postman自動更新了已發(fā)布的API文檔

參考資料

• 主要參考：Github: api_tool_postman
• Manage environments
• postman-變量/環(huán)境/過濾等 - 簡書
• Postman 使用手冊 3——環(huán)境變量 - 簡書
• postman 使用之四：切換環(huán)境和設置讀取變量 - 喬葉葉 - 博客園