前端驅動的接口數據檢查、文檔生成、mock 以及接口自動化測試

咱們項目開發時，時常面臨這樣的問題，在接口對接時，先後端脫鉤，並行開發時相互限制拖慢開發效率。以往，這件事經常是後端主導的，後端同窗輸出的接口不能知足前端需求，這也是爲何 graghql 火起來的緣由。如何去優化這個場景呢？通過一段時間的探索以後，最終我找到了以下的解決方案，在這個方案中，有前端同窗來主導這個過程。經過這個方案，但願和廣大開發者共同思考這一問題。

你能夠在這裏閱讀到詳細的文檔。

數據類型檢查、文檔、mock以及測試

類型模塊

利用 tyshemo 撰寫項目中須要作類型檢查的類型文件，通常，一個 *.type.js 中包含了多個類型容器，這些容器都對應了本身的數據結構，以及每一個節點上的值的類型。在拋開其餘全部相關環節以外，類型模塊在前端代碼中的做用就是作數據結構、節點類型檢查的。

import { BookType } from './book.type.js'

class Book extends Component {
  request() {
    this.props.request().then(data => {
      Ty.expect(data).to.match(BookType)
      // ...
    })
  }
}複製代碼

在傳統架構中，將數據類型前置到 data service 中，當數據回來的時候就當即作數據檢查，是一種常見方案：

BookService.get = (id) => CommentService.request('GET', '/book/' + id).then(data => {
  Ty.trace(data).by(BookType).catch(error => console.error(error)) // 異步校驗，避免帶來性能損耗
  return data
})複製代碼

類型模塊規定了一個數據的結構，在上面的這個例子中，也就對應了一個接口的返回結果。

import { Dict, Positive } from 'tyshemo'

export const BookType = new Dict({
  name: String,
  price: Positive,
})複製代碼

既然有了接口的數據結構，及其類型，那麼咱們是否能夠生成出該接口的文檔？

文檔服務

當咱們有了類型容器以後，咱們也能夠將這些類型容器的內容，格式化爲描述語言性質的文檔。例如上面的 BookType 能夠格式化爲：

{
  name: string,
  price: positive,
}複製代碼

這是一段純文本，可是它很是清晰的描述了一個對象的全部。那麼，咱們就須要有一個服務來整合接口文檔所須要的東西。

一個接口的文檔描述中，須要包含以下信息：

• 接口別名
• 接口描述
• 接口的請求類型
• 接口的 URL
• 接口的請求參數及其類型
• 接口的返回結構及其類型
• 接口的錯誤及錯誤碼錶

那麼，咱們在配置文檔服務的時候，針對單個接口，咱們就要把上面這些信息所有配置進去。

{
  name: '接口1',
  description: '該接口用於獲取用戶信息',
  method: 'get',
  path: '/users/:id',
  request: RequestType, // 一個類型容器，用於校驗請求參數是否符合類型和結構
  response: ResponseType, // 一個類型容器，用於校驗響應體的類型和結構
  errorMapping: { // 一個 mapping 表，用於列出全部錯誤 code 值碼
    10001: '數據庫鏈接錯誤',
  }, 
}複製代碼

其中 method 和 path 須要按照 expressjs 的路由格式來處理，由於咱們在後面須要用到它們。另外，咱們想要起一個文檔服務，咱們可能還須要對字段進行備註，這時，我找到一種方法，就是在 ResponseType 上掛載一個 __comments 屬性來添加備註信息：

ResponseType.__comments = {
  'name': '書名',
  'price': '價格',
}複製代碼

可是，這種方式實際上是很差的，由於這樣就把備註和源碼分開了，可是，實際上，咱們但願在源碼中經過註釋進行備註。目前我尚未找到運行時的方法去解決這個問題，想到的方案是編譯時經過工具去提取備註，但還未實現。

有了文檔服務，那麼先後端同窗，就能夠對照文檔，按照約定進行開發。

Mock 服務

但文檔並不能解決運行時的問題。前端開發到必定階段的時候，必定要與接口去聯調，有了接口以後，才能進行下一步的操做。這種狀況下，咱們須要一個 mock 服務，在後端沒有開發完時，能夠前端先 mock，完成開發的大部分事情。

既然咱們有了文檔，咱們發現，文檔服務的配置中會規定 method、path 兩項，咱們就能夠利用它們，結合 express 框架，起一個本地服務器。另外就返回的數據，咱們有了對應的類型容器，可不能夠在類型容器的基礎上生成 mock 數據？固然能夠。

例如，咱們能夠將 number 生成一個隨機數，能夠將 string 生成一個隨機字符串，而且經過隨機因子，實現 boolean、ifexist 等不一樣狀況下值可能不一樣的效果。

經過一系列的處理以後，咱們只須要利用配置信息，就能夠對全部的接口進行 mock，當前端向 mock 服務接口發請求的時候，返回 mock 數據。前端最好本身起一個 node 服務，經過代理的形式，攔截本來往正式的後臺接口發請求的路徑，將請求轉發到 mock 服務上去。

測試服務

如今，咱們將視角轉移到後端的同窗身上，咱們切換身份，如今你是後臺開發的同窗。在對照文檔開發過程當中，你可能並不知道本身寫的接口是否正常工做，可是前端的同窗不可能跟着你去進行測試。你可能會選擇使用 postman 來發送假請求，這樣作是能夠的。可是，你須要每次都去假造請求數據，這一點比較麻煩。

在前文中，咱們配置了請求時發送的數據類型容器，那麼，有沒有辦法經過這個容器，生成一個隨機的請求數據呢？固然是能夠的，和 mock 服務生成隨機數據同樣，咱們以 request 配置爲基礎，生成一個請求參數，並經過 method、path 等配置，完成模擬請求。經過這些模擬請求，就能夠判斷本身寫的接口是否正常工做。

此外，咱們再爲測試服務加上自動化測試的功能。

因爲在大部分狀況下，後臺登錄都須要瀏覽器窗口記錄登錄狀態，所以，我將測試服務設計爲前端瀏覽器能力，而非後臺的測試平臺。經過一個虛擬的定時任務，反覆的構造假數據向後臺接口發送請求，以此來統計請求成功和失敗的數量。在測試階段，這也會有幫助。

統一維護類型

前端對這些類型具備強依賴，類型文件會被直接使用到前端代碼中，用來做爲運行時的類型檢查。（可是在產品階段這不是必須的，能夠經過工具，將類型檢查代碼從原始代碼中去掉。）所以，維護類型文件的主要工做是前端。可是，這並不表明前端同窗能夠任意修改類型文件，修改類型文件意味着對服務端返回結果的修改，但若是在後臺同窗未知情的狀況下這樣作，最終會出問題。固然，因爲有了上述三個服務的保證，這個問題通常能夠在開發階段就反饋出來。

後臺的同窗，也能夠參與到類型文件的維護中。在真實場景中，前端同窗主要維護請求相關的接口類型文件，然後端同窗主要維護提交接口的類型文件。

經過 git 管理類型文件，設置 hook，當類型文件更新以後，觸發 CI 任務，將新的類型文件部署到服務器上，這樣就能夠完成上述 3 個服務的同時更新。

小結

本文基於 TySheMo 體系去解決接口的數據類型、Mock 等問題，是出於對實際工做中需求的思考，力求將整個解決方案作到最小化，輕量化，隨時可拋棄，而不影響原有的業務邏輯。固然，這裏面還有一些問題還沒有解決，若是你有興趣，能夠參與到該項目中，一塊兒改進它。