需要介面管理的你瞭解一下？

聞人的技術部落格發表於2019-07-07

需要介面管理的你瞭解一下？

前言

在日常的開發模式裡，前端負責頁面和動態指令碼的處理，服務端負責業務邏輯和介面的實現。當前端需要服務端提供的介面實現動態資料展示和互動時，服務端完成介面開發後會提供一個介面文件給到前端按照文件規範再進行開發。這樣模式下往往會出現兩種情況：一種是往前端開發的進度往與服務端開發的進度不會完全同步，這就存在了一方等待另一方的情況，這多少會影響整體專案開發進度；另一種就是當前端對接不同的服務端人員所開發的介面，如果沒有了統一的介面文件規範，每個人輸出的介面文件都不盡相同，在後期對專案介面的更新和維護會是很大的時間成本。

所以很有必要有一個前後端通用的介面管理平臺，簡化介面對接和維護的流程。前後端可以通過介面管理平臺，制定介面資料和格式，然後通過模擬資料生成假介面，前後端再各自獨立開發，直至雙方都開發完成後對接真實介面資料進行微調即可。並且通過介面管理平臺，開發人員可以更便捷地管理專案所有介面資料。

這裡本文將主要認識學習一下目前國內開源較火的介面管理平臺 YApi，看如何使用它幫助我們提高開發效率和便捷對介面的管理。

本文不會描述 YApi 的安裝部署過程，想要詳細瞭解如何部署YApi可以參見文末提供的參考連結：YApi 安裝部署，使用 Docker 構建 Yapi

YApi 介紹

YApi 是一個可本地部署的、打通前後端及QA的、視覺化的介面管理平臺，以開發、產品、測試人員提供更優雅的介面管理服務為目標，該專案由去哪兒網大前端技術團隊開源的，託管在 Github 上，已經 9000 多星。

YApi 作為 API 管理平臺主要提供三大塊功能：

  • 專案管理：提供基本的專案分組，專案管理，介面管理功能，成員許可權管理
  • 介面管理：提供友好的介面文件，支援多人協作介面編輯功能，以及類 Postman 測試工具便於高效除錯介面
  • Mock 服務：基於Mock.js，通過隨機資料生成，模擬各種介面資料，充分發揮前後端分離的優勢。

什麼是Mock.js

Mock.js是一個模擬資料生成器，幫助前端開發和原型與後端進度分離，減少一些單調，特別是在編寫自動化測試時。

--- mock.js那點事(上)

當然 YApi 還有很多強大的功能，比如自動化測試，外掛機制，二次開發等等。

下圖是YApi 官方提供了使用 YApi 的工作流程，從這裡可以簡單瞭解下如何在日常開發中使用 YApi。

需要介面管理的你瞭解一下？

第一個 YApi

登入註冊

使用 YApi 前，必須要先有登入賬號，所以一開始需要在所搭建的 YApi 網站上註冊一個賬號,註冊成功就可以用使用者名稱或者郵箱進行登入。

需要介面管理的你瞭解一下？

註冊成功後就會自動登入進入 YApi 首頁，後面再次使用就可以直接用賬號登入了。

需要注意的是作為新註冊的使用者，沒有任何分組與專案的許可權，只能對“公開專案” 的介面進行搜尋、瀏覽 ，此時需要聯絡平臺管理員將你加入對應專案。

下圖為一個正常賬戶登入 YApi 首頁的基本內容：

需要介面管理的你瞭解一下？

  1. 首頁頭部展示了當前所在的位置、搜尋框、新建專案、檢視文件和使用者資訊。

  2. 首頁左側展示分組資訊，“分組”是“專案”的集合，只有超級管理員可以管理分組。

  3. 首頁右側是分組下的專案和成員列表，點選左側的某個分組，右側會出現該分組下的專案和成員資訊。

  4. 點選專案右上角的星星即可關注專案，關注的專案可以在“我的關注”頁面檢視。

  5. 點選頭像進入“個人中心”，允許檢視和修改個人資訊。

專案介面

首先在專案列表選擇一個專案進入(如果沒有可用的專案，一種方式是找管理員分配專案許可權，一種是在左上角點選 "新增專案" 新建一個專案），進入專案後可大致看到如下內容：

image-20190702224455234

  1. 介面列表，展示該專案的所有介面名稱，並且按照資料夾分類，預設都在公共分類下，也可以自定義新增分類。
  2. 測試集合，用於儲存介面執行正常的資料資訊和介面狀態，便於後續直接使用測試集合中的介面測試。
  3. 新增介面，為專案新增介面，預設在公共分類下，需要指定介面名，請求方式和介面路徑，儲存後自動新增到介面列表下。
  4. 用於介面資料的匯入匯出，便於介面資料的遷移歸檔。
  5. 對專案資訊的基本設定，如環境地址，介面路徑，Mock 設定等。

現在我們再來看下一個簡單介面的頁面展示內容：

WechatIMG908

介面資訊框內有四個皮膚可以切換，分別為預覽，編輯，執行和高階 Mock，我們在編輯皮膚裡可以通過介面的請求方式，請求資料，響應資料，介面描述等資訊進行編輯，儲存後都會在預覽皮膚內清晰展示出來，當需要進行介面測試時就需要在執行皮膚裡操作，裡面的操作方式跟 Postman 很相似，相信使用過 Postman 的小夥伴應該能很快上手。

注意：使用介面測試服務時，如果是 Chrome 瀏覽器 ，需安裝測試增強外掛,官方也提供了下載地址和安裝教程。

這裡有一個小技巧可以分享下：每次進入介面的執行皮膚，上次使用請求引數都會被情況，每次都需要重新填寫，如果請求介面引數一多就十分繁瑣；這裡我們可以把測試過的介面通過儲存按鈕加入到測試集合中，後面可以直接在測試集合中找到所記錄的介面和有效的請求引數，並且能直接使用。

image-20190704082517792

高階Mock 一欄則是對介面模擬資料的設定，具體用法在後面會詳細介紹。

到這裡，YApi 的簡單使用介紹完畢，使用 YApi 進行基本的介面測試和維護應該問題不大了，後續介紹 YApi 的更高階用法和最佳實踐。

Mock 介面

本節主要描述如何通過 YApi 的 Mock 服務模擬介面的資料。

首先在介面皮膚裡選擇高階Mock一欄，選擇新增期望來定義所實現模擬的條件和資料。

image-20190706151957646

新增期望時分為兩部分，一塊是填關於期望的基本資訊，如名稱，白名單IP，匹配的引數等，另外一塊就是期望模擬的響應資料，如響應頭資訊，響應體資料，甚至響應時間也可以設定。

在這裡設定響應體資料時，除了使用常規的固定假資料返回，我們可以使用 Mock.js 支援的語法，讓假資料隨機生成，例如下方的示例模擬一個簡單的響應資料： code 為 200 或者 400，message 為重複出現 1~10次的測試兩次。

image-20190706152640885
儲存之後，我們對介面的 Mock 地址*（預覽皮膚中 Mock 地址連結）*進行多次請求就隨機獲得以下的請求資料：

{
"code": 200,
"message": "測試測試測試",
"data": {}
}

{
"code": 400,
"message": "測試測試測試測試測試測試",
"data": {}
}
複製程式碼

當然除了這樣方式定義模擬資料的生成，還有許多豐富的形式，具體的資料定義語法可以參見 Mock.js 提供的官方示例：mockjs.com/examples.ht…

最佳實踐

介面分級

YApi 以專案為單位進行介面的管理，基於此還提供的分類的功能，新生成的介面都有預設的分類為公共分類。

為了能更清晰，更直觀有效地管理介面，我們可以從專案的業務角度出發，在 YApi 中將業務轉換為介面分類，每個業務分類下管理各自相關的介面，而一些公共介面統一在公共分類中管理，比如下圖所示，將訂單業務和支付業務分別生成各自的介面分類，在該分類下都是跟自身業務緊密相關的介面。

image-20190706163548920

環境配置

當日常開發中一個程式都會有不同環境要求，介面請求的地址也不同，為了便於多環境介面的切換，我們可以在專案設定的環境配置 一項新增該專案下介面的多個環境，並且這裡增加了全域性 header，專案中設定全域性 header 值。

image-20190706154822768

除此之外，使用者可以在每個環境配置項中定義 global 全域性變數的名稱和值, 介面執行或者測試集合裡面可以通過 {{ global.Name }} 來訪問當前環境變數下定義的全域性變數。

設定儲存之後，我們就可以在該專案下任一介面的執行皮膚裡切換環境地址，如下

image-20190706155307573

請求配置

YApi 支援 pre-script, 就是通過自定義 js 指令碼方式改變請求的引數和返回的 Response 資料，而這個功能可以滿足當我們請求和響應的資料都是通過加密處理的使用場景。

請求配置的位置同樣在專案設定裡，針對專案的所有介面生效，對外提供公共變數 context 物件包含的請求和響應的所有資料 。

image-20190706162341811

如果我們需要在一組介面的 URL 上增加一個公共的 token 引數，可以在 Pre-request Script 裡寫如下指令碼：

carbon

而如果我們需要修改響應資料中某個值進行修改，可以填寫如下 Pre-response Script 裡寫如下指令碼：

carbon

另外，全域性變數 context 還提供的工具函式，讓我們使用：

工具函式

結合工具函式，我們就可以進行介面請求時和響應時的加密處理，例如我們需要對響應體中 data 資料進行 Base64 加密，可以定義如下指令碼：

carbon

資料匯入匯出

在資料管理上，YApi 提供了簡單而有效的方案來支援資料的匯入和匯出。

YApi 支援快速匯入其他格式的介面資料，以方便快速新增介面。YApi 目前支援 Postman, Swagger, JSON 資料匯入等，方便我們進行介面資料遷移。

而當我們需要把介面分享給非專案組內的人時，我們可以使用資料匯出功能，以 HTML，Markdown 或者 JSON 的格式匯出專案介面文件資料，只需要將文件檔案給到他人就行了。

需要介面管理的你瞭解一下？

結語

本文主要記錄了開源介面管理平臺- YApi的基本介紹和使用。面對多人多專案的團隊開發，有個統一的管理平臺來進行介面管理和維護，還是很有必要的，也是很基礎的，對專案的開發效率提高也有很大幫助，如果你有正在使用 YApi 有更好的使用姿勢或者遇到什麼坑，更或者在使用過其他的介面管理平臺框架，也歡迎留言交流討論?。

需要介面管理的你瞭解一下？

參考

推薦閱讀

相關文章