寶藏發現之API介面高效協作神器Apifox

itxiaoshen發表於2022-05-01
API

概述

背景

Apifox官方地址 https://www.apifox.cn/

前面文章我們已經圍繞微服務展開，缺少一個關鍵前置流程，那就是API介面設計，而在API介面設計開始前本篇先推薦一個非常好用的國人開發工具，它就是Apifox，免費只需註冊就可使用，如需私有化部署再購買，絕大部分人使用場景都可直接使用免費版，無任何限制，相當給力。相信大部分API設計會採用Swagger或Yapi管理 API 文件，後端開發人員肯定是使用過Postman來做API介面聯調（介面是英文版，如果要漢化還得另外處理）、而同時前端開發人員也會使用Mock.js的Mock API 來模擬接收後端返回資料進行同步開發，測試人員使用JMeter做API自動化測試等等。

image-20220422155710694

不用驚訝，Apifox提供一整套解決方案，，Apifox = Postman + Swagger + Mock + JMeter。Apifox 通過一套系統、一份資料，解決多個系統之間的資料同步問題。只要定義好 API 文件，API 除錯、API 資料 Mock、API 自動化測試就可以直接使用，無需再次定義；API 文件和 API 開發除錯使用同一個工具，API 除錯完成後即可保證和 API 文件定義完全一致。高效、及時、準確！

image-20220422155807371

功能特性

官網說明特性包含API 文件設計、API 除錯、API 自動化測試、API 資料 Mock、CI 持續整合、資料庫操作、自動生成程式碼、支援 HTTP、TCP、RPC、資料匯入/匯出、團隊協作。如下為官網首頁部分功能特性，詳細可以查閱官網

image-20220422154548529

Apifox前期可稱為Apifirst,實現了以下幾個亮點功能

  • 後端、前端、測試團隊可以同步開始工作，而不需要互相等待；
  • 使用基於API的自動Mock、程式碼自動生成和自動化測試工具，大幅提升開發效率；
  • 開發的各個角色都會獲得更好的工作體驗；
  • API可以在不同的專案中重複使用，提高開發效率；
  • 新人更容易熟悉專案，方便團隊規模的擴大；
  • 與外部團隊的協作也更加順暢。

團隊協作流程

  • 設計階段

    • 根據需求文件討論確定介面設計思路。
    • 介面設計者在Apifox上定義好文件初稿。
    • 介面評審環節，前後端一起評審、完善後介面文件，定好介面用例。

  • 開發階段

    • 前端 使用系統根據介面文件自動生成的 Mock 資料進入開發，無需手寫 mock 規則。
    • 後端 使用介面用例 除錯開發中介面，只要所有介面用例除錯通過，介面就開發完成了。如開發過中介面有變化，除錯的時候就自動更新了文件，零成本的保障了介面維護的及時性。
    • 後端 每次除錯完一個功能就儲存為一個介面用例。
    • 測試人員 直接使用介面用例測試介面。

  • 聯調和測試階段

    • 所有介面開發完成後，測試人員（也可以是後端）使用集合測試功能進行多介面整合測試，完整測試整個介面呼叫流程。
    • 前後端 都開發完，前端從Mock 資料切換到正式資料，聯調通常都會非常順利，因為前後端雙方都完全遵守了介面定義的規範。
    • 測試可以使用測試套件進行自動化迴歸測試和效能測試。

安裝

安裝

官網提供客戶端安裝版本和 Web 端版本使用，官網也推薦使用客戶端版本，支援Windows、MacOS、Linux，開始下載 Windows（64 位）的版本，安裝即可。

文件

官網文件地址 https://www.apifox.cn/help/

Apifox B站視訊 https://space.bilibili.com/1102302972?spm_id_from=333.337.search-card.all.click

官方提供非常詳細的使用文件，且部分還有視訊教程，此外apihub是一個開放 API 共享平臺，可以找到更多公開 API 專案。Apifox在bilibili上也有一些教程視訊合集。

註冊

雙擊啟動Apifox後，可通過郵箱註冊一個賬號，登入後主頁提供我的團隊、APIHub、我的收藏、最近訪問四大塊功能。在示例團隊裡有一個寵物店的示例專案，可以詳細參考學習，我們下面則以一個實際操作流程來學習下Apifox整體使用。

實戰示例

團隊管理

第一步我們先建立團隊，名稱為ITXS團隊，點選儲存。

image-20220427160234679

  • 團隊名稱可以修改，團隊可以移交（將團隊的所有者許可權移交給其他成員）和解散（務必謹慎，解散後無法找回）。
  • 許可權分為團隊許可權和專案許可權。團隊許可權指成員對團隊操作的許可權，專案許可權指成員對專案操作的許可權。詳細許可權可以查閱官網。
    • 團隊角色：所有者、管理者和普通使用者。
    • 專案許可權：管理員、普通成員、只讀成員、禁止訪問的角色。
  • 團隊角色分所有者、管理者和普通使用者。

邀請成員可設定其團隊的許可權和對應專案的專案許可權

image-20220427172920786

受邀請成員在通知欄中點選接受即可

image-20220427173700835

在團隊成員許可權中可以修改成員的許可權和移除成員。

新建專案

建立選課系統示例專案

image-20220427161224481

  • 在團隊下的專案可以修改專案名稱、克隆專案、移動專案、刪除專案、收藏專案（在我的收藏中可以快捷找到）
  • 點選直達專案,啟動Apifox直接進入到這個專案。
  • 新視窗開啟，這個好用，如果我們同時有多個專案的話可以開啟多個專案視窗，同時主視窗也在，剛開始我們開可以一邊參考示例團隊的示例專案。

資料模型

資料模型是可複用的資料結構。在設計資料結構時可以在資料型別直接選擇已經定義好的資料模型。管理資料模型，在使用資料模型前，需要先建立可複用的資料結構。如下圖，根據專案需要，可以先在資料模型下新建，也可以簡單的管理不同資料模型間的關係。資料模型之間也可以相互引用。

當下介面需要部分引用資料模型時，可以在引用的情況下修改，並且不影響原資料模型

  • 當不需要資料模型中的某個欄位時，可以點選隱藏欄位，則介面文件中就不會顯示了
  • 當需要對資料模型中的某個欄位，特殊編輯時，可以點選取消關聯。當然後續也可以恢復關聯
  • 可以引用多個資料模型，並支援資料模型之間拖拽排序

點選直達進入選課系統示例專案，介面建立學生分組，資料模型中也建立基礎和學生分組，在基礎分組中通過在根節點上點選+號逐個欄位建立好系院資料模型，最後點選儲存Depart資料模型。

image-20220429123104073

基礎分組繼續建立專業資料模型，在Depart資料模型是哪個選擇複製，輸出專業資訊，最後點選儲存Major資料模型。

image-20220429123648147

基礎分組繼續建立班級資料模型，點選中間的JSON/XML智慧識別/快捷匯入，確定後可快捷生成資料模型的欄位和推斷出欄位型別

image-20220429124143024

建立學生資料模型

image-20220429143841525

全域性響應

全域性響應主要用來實現返回響應的複用。通常不同介面在某些情況下會返回相同的資料結構，如資源不存在(404)、沒有訪問許可權(401)等，這些建議設定為全域性響應，避免重複編寫，放方便統一管理。

專案設定中全域性響應建立全域性響應，填寫如下

image-20220429175651273

再多建立幾個全域性響應

image-20220429180213252

介面管理

查詢介面

學生資訊查詢介面

介面設計即定義介面文件規範（如介面路徑、引數、返回值、資料結構等）

  • 介面設計：即 新建介面 介面或介面詳情裡的 編輯 介面，用途是 定義介面文件規範，而不是 執行 介面，所以該介面是隻能定義介面基本資訊、引數名及引數說明等，而不能設定引數值。引數值、前置指令碼/後置指令碼 等資訊請在介面執行介面或介面用例介面填寫。
  • 介面執行：即介面詳情裡的 執行 介面，用途是 臨時除錯介面，執行 完後，需要點選儲存為用例，才能將填寫的 引數值、前置指令碼/後置指令碼 等資訊儲存下來；否則關閉 tab 後，這些資訊將會丟失。

介面路徑

  • 介面路徑 建議不要包含 HTTP 協議及域名，這部分建議在 環境管理 的前置URL裡設定，介面除錯時的 URL 會自動加上當前環境的前置URL。
  • 特殊情況需在介面路徑要帶上HTTP 協議及域名的，系統也能支援，但不建議這麼做。介面除錯時，系統如檢測到介面路徑是以http://或https://起始的，會自動忽略當前環境裡前置 URL。
  • Apifox 中的 Path 引數是以大括號包裹起來表示，而非冒號起始表示。正確示例：/pets/{id}，錯誤示例/pets/:id。
  • 介面路徑 不可包含Query 引數（即 URL 中 ?後的引數），Query 引數在下方請求引數部分填寫。

在學生分組下建立查詢學生資訊介面

image-20220429145001966

點選修改文件，在根節點下新增響應的欄位資料，點選儲存按鈕

image-20220429150212851

新增一個響應示例，點選自動生成，可以看到Apifox已經給我們Mock出來很多正常使用的資料。

image-20220430195217999

點選執行，切換為Mock服務，點選傳送，響應資料內容如下，這個是Mock出來的資料，最後點選儲存為用例為後續測試複用。

  • 在介面執行的時候，介面路徑、引數名會自動從介面設計讀取，無需手動輸入，引數值預設會讀取介面設計裡的示例值，可手動修改。
  • 填寫好引數後，點選傳送按鈕即可執行。
  • 儲存為用例是將當前填寫的引數儲存起來，方便下次或者其他人用來除錯介面。
  • 儲存為用例後，介面用例會顯示在左側樹狀選單裡介面的下一級。
  • 介面用例是非常有用的，建議每次執行後都儲存為用例，後續用介面用例來除錯介面是非常高效的。
  • 通常一個介面會有多種情況用例，比如引數正確用例、引數錯誤用例、資料為空用例、不同資料狀態用例等等。
  • 返回響應是用來給系統校驗介面請求後返回的資料是否符合對應 Response 裡定義的資料結構，免去人眼識別，提高效率和準確性。
  • 資料結構校驗結果系統會根據選擇的返回響應的資料結構，自動分析執行後返回的資料是否正確，並且給出詳細的錯誤提示。
  • 斷言：後置操作支援新增斷言，可對介面返回的資料（或響應時間）設定斷言，判斷是否符合預期。
  • 提取變數後置操作支援新增提取變數，可從介面返回結果裡提取資料，設定到變數（臨時變數/環境變數/全域性變數），方便其他介面執行的時候直接使用。

image-20220429150417298

選擇全域性響應記錄不存在，點選傳送測試，結果如下，最後儲存為記錄不存在用例。

image-20220429181105343

回到文件TAB頁，可以看到已經MOCK區域有兩條記錄

image-20220430200051288

複製URL我們直接到瀏覽器上訪問下，可以看到已經在本地啟動Mock服務

[外鏈圖片轉存失敗,源站可能有防盜鏈機制,建議將圖片儲存下來直接上傳(img-3LUSnGoD-1651340301671)(F:\creation\markdown\article\寶藏發現之API介面高效協作神器Apifox\寶藏發現之API介面高效協作神器Apifox.assets\image-20220430195909497.png)]

實時更新介面的狀態，不同狀態的顏色不同，有利於團隊協助進行，相應人員可以根據狀態進行篩

image-20220430201536651

需要更多狀態管理時可以到專案設定，功能設定中借樓狀態進行設定

image-20220430201831543

建立期望

建立記錄不存在的測試用例，在介面中切換高階Mock，點選新建期望，設定路徑引數為3時作為記錄不存在

image-20220429174842861

image-20220429180750319

新建介面

學生資訊新建介面

新建學生資訊介面，為Post請求，填寫Body資料，在返回響應的全域性響應中關閉，狀態碼為201，點選儲存（記得修改文件後一定要點選儲存再操作執行）

image-20220429200705208

點選執行並儲存為成功用例

image-20220429200753554

修改介面

修改學生資訊

建立修改學生資訊介面為PUT型別，使用json匯入引數，儲存為介面

image-20220429201359418

建立一個驗證錯誤返回響應

image-20220429201703346

驗證錯誤響應

image-20220429202441124

刪除介面

刪除學生資訊介面

建立刪除學生資訊介面型別為DELETE，儲存

image-20220429202813171

儲存為成功用例介面

image-20220429203237708

在返回響應成功（200）新增code欄位，新增響應示例，點選自動生成，並儲存為成功用例

image-20220429203614549

建立快捷請求

快捷請求可以輸入完整的URL，填寫相關的引數

image-20220429205048979

自動化測試

測試用例

新增用例有兩種方式：從介面匯入和從介面用例匯入 (推薦)

  • 從【介面】匯入：根據介面引數自動生成一個用例，其引數值為空，需要手動填寫。
  • 從【介面用例】匯入：有兩種模式複製和繫結。將介面用例以複製的方式匯入，介面用例裡的引數也會一同複製過來，和原來用例資料相互獨立，各自改動後互不影響。將介面用例以繫結的方式匯入，會直接引用原來的用例，兩邊的改動都會相互實時同步。
  • 從介面匯入後，需要手動設定介面引數，否則執行的時候，介面引數是空的。
  • 從介面用例匯入後，會同步匯入介面用例裡的引數，會方便很多。

建立測試用例

image-20220429205320101

點選詳情，從介面用例匯入資料，也可以從介面中匯入用例

image-20220429205517481

匯入，點選執行

image-20220429205629892

檢視測試結果

image-20220429205714375

測試套件

測試套件為測試用例的集合，每個測試套件包含多個測試用例。主要用途：

  • 實現測試用例的複用。
  • 業務流程複雜時，可避免將所有步驟都寫在單個用例裡，防止造成單個用例裡的步驟過多，難以管理。

選擇一組測試用例，執行輸出測試結果

image-20220429210039408

效能測試

  • 執行測試用例的時候，設定執行緒數大於1即可實現效能測試。
  • 執行緒數即同時【併發】執行的執行緒數，每個執行緒都會按順序執行選中的所有步驟。
  • Apifox CLI 是 Apifox 的命令列執行工具，主要用來做持續整合和壓力測試，其壓力測試功能目前正在開發中，敬請期待！
  • 測試用例和測試套件可以匯出JMeter`格式資料，然後可以匯入 JMeter 做效能測試。

測試資料

測試用例和測試套件支援測試資料集。當用例或套件執行時，系統會迴圈執行資料檔案裡所有的資料集，並且會將資料集裡的資料賦值給對應的變數。

  1. 每個資料集可包含多個變數，介面執行時 使用變數 的地方會讀取對應的值（變數優先順序：臨時變數 > 測試資料變數 > 環境變數 > 全域性變數）。
  2. 可建立多個資料集，系統會遍歷執行所有的資料集（每個資料集都會被執行一次）。
  3. 資料集雲端同步，成員之間共享測試資料。
  4. 可根據不同環境設定不同的資料集。

測試報告

執行完成後，如圖所示，可以看到哪些介面沒有通過測試，可以點選對應的介面展開詳情；點選更多詳情，可以檢視該介面的執行結果，方便定位問題。執行結束後檢視之前的測試報告，也可以匯出。

image-20220429210237724

Mock

功能說明

Mock 功能可以根據介面/資料結構定義、Mock規則配置、Mock 期望配置，自動生成模擬資料，且使用者可以根據需要靈活構造各種結構的介面資料。通常情況 Apifox 零配置即可生成非常人性化的 mock 資料：

  • Apifox 根據介面定義裡的資料結構、資料型別，自動生成 mock 規則。
  • Apifox 內建 智慧 Mock功能，根據欄位名、欄位資料型別，智慧優化自動生成的 mock 規則。如：名稱包含字串image的string型別欄位，自動 mock 出一個圖片地址 URL；包含字串time的string型別欄位，自動 mock 出一個時間字串；包含字串city的string型別欄位，自動 mock 出一個城市名。
  • Apifox 根據內建規則（可關閉），可自動識別出圖片、頭像、使用者名稱、手機號、網址、日期、時間、時間戳、郵箱、省份、城市、地址、IP 等欄位，從而 Mock 出非常人性化的資料。
  • 除了內建 mock 規則，使用者還可以自定義規則庫，滿足各種個性化需求。支援使用 正規表示式、萬用字元 來匹配欄位名自定義 mock 規則。

零配置一些常見欄位已經自動mock資料

image-20220430202532518

Mock 語法

Apifox Mock 語法完全相容[Mock.js（資料佔位符方式），並擴充套件了一些 Mock.js 沒有的語法（如國內手機號 @phone）。如現有 Mock 語法無法滿足需求，建議使用 正規表示式 @regexp來實現靈活的定製。正規表示式基本能滿足各種特殊場景的需求。

基本寫法

寫法 說明
以@起始的字串 呼叫 Mock 語法規則生成對應的資料。 如生成的資料型別和定義的資料型別不一致，則會自動轉換。
非@起始的字串 資料型別為string時，原樣輸出。 其他資料型別，會將字串自動轉換到對應的資料型別。
特殊字元：null 資料型別允許為null 時，輸出null。 否則自動轉換，如資料型別為string，輸出"null"。
特殊字元：true 資料型別為boolean 時，輸出true。 否則自動轉換，如資料型別為string，輸出"true"。
特殊字元：false 資料型別為boolean 時，輸出false。 否則自動轉換，如資料型別為string，輸出"false"。

自動轉換 是使用 javascript 語言預設資料轉換方法進行轉換。其他詳細可以查閱官網

高階MOCK

定義 mock 規則，前面我們介面中已使用自定義mock規則，針對欄位Mock設定裡選擇，還可以像postman一樣的自定義指令碼

image-20220430202812280

  • 資料欄位高階設定裡設定的最大值、最小值、列舉值、Partten、format，也會作為 Mock 規則使用。
  • 高階 mock 的是最靈活的 mock 方式，可實現靈活的自定義資料結構（不受介面資料結構限制），且可以根據不同的請求引數值返回不同的資料設定位置：介面詳情-高階 Mock
  • 優先順序說明：請求 Mock 資料時，規則匹配優先順序：高階 Mock 裡的期望 > 自定義 Mock 指令碼。如果匹配到了高階 Mock 裡的期望，則不呼叫自定義 Mock 指令碼。

智慧MOCK

  • 智慧mock:當介面設計的返回 Response (或資料模型) 裡的欄位未配置 mock 規則時，系統會自動使用智慧 Mock 規則來生成資料，以實現使用時零配置即可 mock 出非常人性化的資料。設定位置：專案設定-智慧 Mock 設定的自定義規則及內建規則。
    • 自定義規則：使用者可新建自定義規則，滿足各種個性化需求。支援使用 正規表示式、萬用字元 來匹配欄位名自定義 mock 規則。
    • 內建規則：系統內建常用 mock 規則庫，可自由決定是否開啟內建規則。
    • 優先順序：自定義規則優先順序高於內建規則，可新增自定義規則來覆蓋系統內建規則。

智慧Mock我們在前面查詢介面的建立期望也簡單介紹了，總體說MOCK功能是非常的強大。

生成線上文件

在 API 開發、溝通、協作中，邏輯上是以 API 文件為標準的，但實際操作中，存在以 Word、PDF 格式的檔案傳來傳去的問題。為此我們提倡以線上文件的形式，提高團隊之間的溝通效率，線上分享裡新建分享

image-20220429212120905

建立後複製連結發給其他團隊就可以使用了

image-20220429212235423

標籤功能

介面修改文件中設定標籤，輸入則增加標籤，儲存，然後再左側可以根據標籤進行篩選。

image-20220430201108439

新建分享中可以指定標籤設定分享範圍

image-20220430201301349

環境管理

一個專案在不同的階段會處於不同的環境中，比如開發環境、測試環境、生產環境，通常不同的環境有不同的前置 URL、介面引數值等。因環境不同而頻繁的更改介面前置 URL 及引數，是非常的麻煩的。 Apifox 的環境管理功能，只需在不同的環境設定不同的前置 URL 及引數，在不同環境中測試時，直接切換環境即可。如果預設環境不夠用還可以新建環境。

快速切換前置URL，在管理環境比如在測試環境裡新增服務，如學生和老師都有不同域名，點選儲存

image-20220430212328591

回到查詢學生資訊介面修改文件，我們看到服務（前置URL）可以選擇手動繫結學生服務

image-20220430212913738

這是在測試環境執行可以看到整個請求已經帶上前置URL了

image-20220430213055733

後置操作

後置操作支援新增斷言，可對介面返回的資料（或響應時間）設定斷言，判斷是否符合預期。

在執行中後置操作中新增後置操作，斷言名稱存在，儲存用例

image-20220501002000151

執行檢視結果，顯示斷言結果已存在，前置操作也是如此

image-20220501002109508

  • 後置操作支援新增提取變數`，可從介面返回結果裡提取資料，設定到變數（臨時變數/環境變數/全域性變數），方便其他介面執行的時候直接使用。
  • 前置操作、後置操作支援新增資料庫操作，可讀寫資料庫資料，查詢結果可在介面請求引數、斷言、自定義指令碼等場景中使用。目前支援MySQL、SQL Server、Oracle、PostgreSQL，未來會支援更多資料庫型別。
  • 使用變數時，讀取物件或陣列型別變數裡的屬性值寫法為{{allUser[0].name}}或{{user.name}}，遵循JSON Path語法規範，只需將JSON Path裡的$符號替換為變數名既可。

環境變數 / 全域性變數 / 臨時變數

和程式語言類似，變數是允許在多個地方重複使用的值。不同的介面用例（請求引數、指令碼等）可以引用相同的變數值，只需要更改一次變數值，就能改變所有引用了該變數的相關值。使用變數可以大幅提升工作效率。

image-20220501010125319

在新建學生資訊結構修改文件，增加body引數，在請求引數的示例值的位置，滑鼠移動到輸入框上時，會顯示一個魔法棒的圖示（動態值有動態變數、常量、變數等設定），選擇或者填入變數名，儲存後點選執行

image-20220501011523272

在實際請求檢視到token的值為全域性變數設定的值

image-20220501011811684

其他功能

官方還提供很多其他的功能，如動態變數、隨機引數、全域性引數、socket報文介面、匯入資料、匯入抓包資料、匯出資料、程式碼生成、介面之間傳遞資料、使用指令碼、持續整合、外掛等等，這些有興趣可以前往官網繼續學習，好了，本篇就先到這裡

**本人部落格網站 **IT小神 www.itxiaoshen.com

相關文章