Postman 介面測試神器
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 文件。
- Collection
- 滑鼠移動到某個 Collection,點選 三個點
- Publish Docs
- Publish
- 得到 Public URL
- 別人開啟這個 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
即可看到更新後的內容: