 ## 前言 在日常的開發模式里，前端負責頁面和動態腳本的處理，服務端負責業務邏輯和介面的實現。當前端需要服務端提供的介面實現動態數據展示和交互時，服務端完成介面 ...
 ## 前言 在日常的開發模式里，前端負責頁面和動態腳本的處理，服務端負責業務邏輯和介面的實現。當前端需要服務端提供的介面實現動態數據展示和交互時，服務端完成介面開發後會提供一個介面文檔給到前端按照文檔規範再進行開發。這樣模式下往往會出現兩種情況：一種是往前端開發的進度往與服務端開發的進度不會完全同步，這就存在了一方等待另一方的情況，這多少會影響整體項目開發進度；另一種就是當前端對接不同的服務端人員所開發的介面，如果沒有了統一的介面文檔規範，每個人輸出的介面文檔都不盡相同，在後期對項目介面的更新和維護會是很大的時間成本。 所以很有必要有一個前後端通用的介面管理平臺，簡化介面對接和維護的流程。前後端可以通過介面管理平臺，制定介面數據和格式，然後通過模擬數據生成假介面，前後端再各自獨立開發，直至雙方都開發完成後對接真實介面數據進行微調即可。並且通過介面管理平臺，開發人員可以更便捷地管理項目所有介面數據。 這裡本文將主要認識學習一下目前國內開源較火的介面管理平臺 YApi，看如何使用它幫助我們提高開發效率和便捷對介面的管理。 > 本文不會描述 YApi 的安裝部署過程，想要詳細瞭解如何部署YApi可以參見文末提供的參考鏈接：[YApi 安裝部署](https://hellosean1025.github.io/yapi/devops/index.html)，[使用 Docker 構建 Yapi](https://www.jianshu.com/p/a97d2efb23c5) ## YApi 介紹 YApi 是一個可本地部署的、打通前後端及QA的、可視化的介面管理平臺，以開發、產品、測試人員提供更優雅的介面管理服務為目標，該項目由去哪兒網大前端技術團隊開源的，托管在 [Github](https://github.com/YMFE/yapi) 上，已經 9000 多星。 YApi 作為 API 管理平臺主要提供三大塊功能： - 項目管理：提供基本的項目分組，項目管理，介面管理功能，成員許可權管理 - 介面管理：提供友好的介面文檔，支持多人協作介面編輯功能，以及類 Postman 測試工具便於高效調試介面 - Mock 服務：基於[Mock.js](http://mockjs.com/)，通過隨機數據生成，模擬各種介面數據，充分發揮前後端分離的優勢。 > **什麼是Mock**.**js** > > **Mock**.**js是**一個模擬數據生成器，幫助前端開發和原型與後端進度分離，減少一些單調，特別**是**在編寫自動化測試時。 > > --- [mock.js那點事(上)](https://juejin.im/post/58f9eec0a22b9d00658ee4b7) 當然 YApi 還有很多強大的功能，比如自動化測試，插件機制，二次開發等等。 下圖是YApi 官方提供了使用 YApi 的工作流程，從這裡可以簡單瞭解下如何在日常開發中使用 YApi。  ## 第一個 YApi ### 登錄註冊 使用 YApi 前，必須要先有登錄賬號，所以一開始需要在所搭建的 YApi 網站上註冊一個賬號,註冊成功就可以用用戶名或者郵箱進行登錄。  註冊成功後就會自動登錄進入 YApi 首頁，後面再次使用就可以直接用賬號登錄了。 需要註意的是作為新註冊的用戶，沒有任何分組與項目的許可權，只能對“公開項目” 的介面進行搜索、瀏覽 ，此時需要聯繫平臺管理員將你加入對應項目。 下圖為一個正常賬戶登錄 YApi 首頁的基本內容：  1. 首頁頭部展示了當前所在的位置、搜索框、新建項目、查看文檔和用戶信息。 2. 首頁左側展示分組信息，“分組”是“項目”的集合，只有超級管理員可以管理分組。 3. 首頁右側是分組下的項目和成員列表，點擊左側的某個分組，右側會出現該分組下的項目和成員信息。 4. 點擊項目右上角的星星即可關註項目，關註的項目可以在“我的關註”頁面查看。 5. 點擊頭像進入“個人中心”，允許查看和修改個人信息。 ### 項目介面 首先在項目列表選擇一個項目進入(如果沒有可用的項目，**一種方式是找管理員分配項目許可權**，一種是在左上角點擊 **"添加項目"** 新建一個項目），進入項目後可大致看到如下內容：  1. 介面列表，展示該項目的所有介面名稱，並且按照文件夾分類，預設都在公共分類下，也可以自定義添加分類。 2. 測試集合，用於保存介面運行正常的數據信息和介面狀態，便於後續直接使用測試集合中的介面測試。 3. 添加介面，為項目添加介面，預設在公共分類下，需要指定介面名，請求方式和介面路徑，保存後自動添加到介面列表下。 4. 用於介面數據的導入導出，便於介面數據的遷移歸檔。 5. 對項目信息的基本設置，如環境地址，介面路徑，Mock 設置等。 現在我們再來看下一個簡單介面的頁面展示內容：  介面信息框內有四個面板可以切換，分別為預覽，編輯，運行和高級 Mock，我們在**編輯**面板里可以通過介面的請求方式，請求數據，響應數據，介面描述等信息進行編輯，保存後都會在**預覽**面板內清晰展示出來，當需要進行介面測試時就需要在**運行**面板里操作，裡面的操作方式跟 Postman 很相似，相信使用過 Postman 的小伙伴應該能很快上手。 > 註意：使用介面測試服務時，如果是 Chrome 瀏覽器 ，需安裝測試增強插件,官方也提供了下載地址和安裝教程。 這裡有一個小技巧可以分享下：每次進入介面的運行面板，上次使用請求參數都會被情況，每次都需要重新填寫，如果請求介面參數一多就十分繁瑣；這裡我們可以把測試過的介面通過**保存**按鈕加入到測試集合中，後面可以直接在測試集合中找到所記錄的介面和有效的請求參數，並且能直接使用。  高級Mock 一欄則是對介面模擬數據的設置，具體用法在後面會詳細介紹。 到這裡，YApi 的簡單使用介紹完畢，使用 YApi 進行基本的介面測試和維護應該問題不大了，後續介紹 YApi 的更高級用法和最佳實踐。 ## Mock 介面 本節主要描述如何通過 YApi 的 Mock 服務模擬介面的數據。 首先在介面面板里選擇**高級Mock**一欄，選擇添加期望來定義所實現模擬的條件和數據。  添加期望時分為兩部分，一塊是填關於期望的基本信息，如名稱，白名單IP，匹配的參數等，另外一塊就是期望模擬的響應數據，如響應頭信息，響應體數據，甚至響應時間也可以設置。 在這裡設置響應體數據時，除了使用常規的固定假數據返回，我們可以使用 Mock.js 支持的語法，讓假數據隨機生成，例如下方的示例模擬一個簡單的響應數據： `code` 為 200 或者 400，`message` 為重覆出現 1~10次的測試兩次。 保存之後，我們對介面的 Mock 地址*（預覽面板中 Mock 地址鏈接）*進行多次請求就隨機獲得以下的請求數據： ```json { "code": 200, "message": "測試測試測試", "data": {} } { "code": 400, "message": "測試測試測試測試測試測試", "data": {} } ``` 當然除了這樣方式定義模擬數據的生成，還有許多豐富的形式，具體的數據定義語法可以參見 Mock.js 提供的官方示例：[http://mockjs.com/examples.html](http://mockjs.com/examples.html) ## 最佳實踐 ### 介面分級 YApi 以項目為單位進行介面的管理，基於此還提供的分類的功能，新生成的介面都有預設的分類為公共分類。 為了能更清晰，更直觀有效地管理介面，我們可以從項目的業務角度出發，在 YApi 中將業務轉換為介面分類，每個業務分類下管理各自相關的介面，而一些公共介面統一在公共分類中管理，比如下圖所示，將訂單業務和支付業務分別生成各自的介面分類，在該分類下都是跟自身業務緊密相關的介面。  ### 環境配置 當日常開發中一個程式都會有不同環境要求，介面請求的地址也不同，為了便於多環境介面的切換，我們可以在項目設置的`環境配置` 一項添加該項目下介面的多個環境，並且這裡增加了全局 `header`，項目中設置全局 `header` 值。  除此之外，用戶可以在每個環境配置項中定義 `global` 全局變數的名稱和值, 介面運行或者測試集合裡面可以通過 `{{ global.Name }}` 來訪問當前環境變數下定義的全局變數。 設置保存之後，我們就可以在該項目下任一介面的運行面板里切換環境地址，如下 ### 請求配置 YApi 支持 `pre-script`, 就是通過自定義 js 腳本方式改變請求的參數和返回的 Response 數據，而這個功能可以滿足當我們請求和響應的數據都是通過加密處理的使用場景。 請求配置的位置同樣在項目設置里，針對項目的所有介面生效，對外提供公共變數 `context` 對象包含的請求和響應的所有數據 。  如果我們需要在一組介面的 URL 上增加一個公共的 `token` 參數，可以在 Pre-request Script 里寫如下腳本： 而如果我們需要修改響應數據中某個值進行修改，可以填寫如下 Pre-response Script 里寫如下腳本： 另外，全局變數 `context` 還提供的工具函數，讓我們使用：  結合工具函數，我們就可以進行介面請求時和響應時的加密處理，例如我們需要對響應體中 `data` 數據進行 Base64 加密，可以定義如下腳本： ### 數據導入導出 在數據管理上，YApi 提供了簡單而有效的方案來支持數據的導入和導出。 YApi 支持快速導入其他格式的介面數據，以方便快速添加介面。YApi 目前支持 Postman, Swagger, JSON 數據導入等，方便我們進行介面數據遷移。 而當我們需要把介面分享給非項目組內的人時，我們可以使用數據導出功能，以 HTML，Markdown 或者 JSON 的格式導出項目介面文檔數據，只需要將文檔文件給到他人就行了。  ## 結語 本文主要記錄了開源介面管理平臺- YApi的基本介紹和使用。面對多人多項目的團隊開發，有個統一的管理平臺來進行介面管理和維護，還是很有必要的，也是很基礎的，對項目的開發效率提高也有很大幫助，如果你有正在使用 YApi 有更好的使用姿勢或者遇到什麼坑，更或者在使用過其他的介面管理平臺框架，也歡迎留言交流討論
