基於 mockm 的一款 HBuilderX 插件 - 接口伴侶

使用說明

接口伴侶 是 mockm 的 HBuilderX 輔助工具. 安裝后會在右鍵菜單中添加 接口編輯, 簡易 postman 一系列的功能.

如果不能正常使用, 請先安裝 mockm(點擊查看文檔):

# 查看 node 版本, 目前 mockm 支持 node v10.12.0 到 14.17.0 版本
node -v

# 安裝
cnpm i -g mockm

# 運行
mockm

從配置文件生成接口

也可以從配置文件中快速以編程形式創建接口.

示例 mm.config.js :

module.exports = {
  // proxy: `https://example.com/`, // 代理后端的接口, 如果沒有可不填

  api: {  // 自己編寫的接口

    // 當為基本數據類型時, 直接返回數據, 這個接口返回 {"msg":"ok"}
    '/api/1': {msg: `ok`},

    // 也可以像 express 一樣返回數據
    '/api/2' (req, res) {
      res.send({msg: `ok`})
    },

    // 一個只能使用 post 方法訪問的接口
    'post /api/3': {msg: `ok`},

    // 一個 websocket 接口, 會發送收到的消息
    'ws /api/4' (ws, req) {
      ws.on('message', (msg) => ws.send(msg))
    }

    // 一個下載文件的接口
    '/file' (req, res) {
      res.download(`文件路徑`, `文件名`)
    },

    // 獲取動態的接口路徑的參數 code
    '/status/:code' (req, res) {
      res.json({statusCode: req.params.code})
    },

    //... 更多功能和示例請參考原 mockm 文檔
  },
}

訪問 http://127.0.0.1:9000/api/1 查看效果, 其他接口類似.

打開UI界面 - 接口編輯

如果還沒有真實的接口, 可以通過此功能創建便於前后端參考的 接口|文檔 , 它描述了請求的地址, 方法, 參數的位置, 類型, 響應, 並且可以生成供前端調用的接口.

這里創建的接口稱為 webApi 接口, 與 config.api 中編寫的接口進行合並, 重復時會被后者覆蓋.

mockm 會根據填寫的 字段名, 示例值, 類型 轉換為對應的響應數據, 支持 mockjs 語法.

快捷鍵 ctrl+s 或點擊 method 區域的 action -> save 保存.

默認情況下, 生成的整個數據是一個對象. 如果要精確控制返回值, 可以使用快捷鍵 ctrl+e 或點擊 action -> example 打開的窗口中操作.

使用表格中的數據作為響應

則根據你在表中錄入情況生成數據, 你可以修改返回值為 object 或 array. 為 object 時, 生成規則表示從單個對象中隨機取幾個字段, 為 array 時, 表示返回的數組中有多少個對象.

示例數據是根據表格中錄入的內容配合生成規則形成的, 僅供預覽.

支持自定義響應頭, 以 key:value 形式編寫即可.

注: 表格形式生成的數據 content-type 為 application/json .

以編程方式自定義接口響應

你可使用 js 編寫該接口的邏輯, 例如響應數據根據請求的不同而不同.

與 config.api 的編寫方式對應, 由於需要考慮安全性, web 界面上不支持直接使用某些方法, 例如 fs 模塊. 作為函數使用的時候, 為了方便提供了 tool 全局變量.

• tool 這是一個全局對象
  • libObj - 函數接收到的工具, 例如 mockjs, axios
  • wrapApiData - config.js 數據統一處理函數
  • listToData - 可轉換 table 為數據的函數
  • cur - 當前接口信息

使用歷史記錄作為響應

輸入請求ID, 請求當前接口時, 總是返回所輸入請求ID的響應, 包括 headers 以及其中的測試鏈接也總是一樣的.

批量添加

從文本批量添加

編輯接口時, 雙擊表格中的添加按鈕, 在彈窗中輸入要內容即可, 支持層級, 自動翻譯, mock 數據和類型自動生成.

示例:

昵稱
郵箱
頭像
孩子
- 年齡
- 出生日期
- 手機號

更多示例

這里列出一些常用的業務場景, 方便快速查找.
如果有需要后台接口的地方, 統一假設為 http://192.168.1.18:8080.

如何使后端的接口允許跨域

不需要配置 webpack, 不需要后端人員更改, 不需要瀏覽器插件

這個功能 mockm 默認是支持的, 以最簡方式啟動 mockm 就能擁有此功能, 只要在命令行輸入下面這條命令即可.

mm proxy=http://192.168.1.18:8080

你也可以使用配置文件的方式, 創建 mm.config.js 文件並錄入以下內容, 然后命令行輸入 mm 即可:

module.exports = {
  proxy: `http://192.168.1.18:8080`
}

然后更換原來的請求地址為自己的即可, 例如自己的 IP 為 192.168.1.17 則做以下更改:

• 更改前: http://192.168.1.18:8080/api/
• 更改后: http://192.168.1.17:9000/api/

如何從接口獲取請求信息

當我們需要根據接口傳入的值來返回不同的內容時, 也是很容易:

module.exports = {
  api: {
    '/my/value' (req, res) {
      // req.params 是 url 上的路徑參數
      // req.query 是 url 上的查詢參數
      // req.body 是請求體中的參數
      res.json({desc: `你傳入的值`, data: req.query})
    },
  },
}

接下訪問接口傳入一些 url 參數測試一下 http://localhost:9000/my/value?city=上海 結果為:

{
  "desc": "你傳入的值",
  "query": { "city": "上海" } }

如何快速生成 Restful API

假設我要寫一個博客文章的列表, 並且要實現添加文章, 查詢文章, 分頁, 模糊搜索, 刪除, 修改等各種功能的接口. 那么只需添加以下內容:

module.exports = {
  db: {
    'blogs': [
      {
        id: 1,
        content: `mockm 是一款便於使用, 功能靈活的接口工具. 看起來不錯~`,
        title: `認識 mockm 的第一天`,
      },
    ],
  },
}

這時候上面要實現的所有接口已經實現了.
這里我用 http 作為請求工具簡單表示幾個功能, 你可以使用你喜歡的工具發送請求.

# 查看 id 為 1 的博文詳情
http :9000/blogs/1

# 創建一篇關於同事的文章
http post :9000/blogs title=同事的一天 content=今天他的生活還是同樣的苦澀

# 獲取所有文章
http :9000/blogs

# 查詢所有含有 `苦澀` 的文章
http :9000/blogs?q=苦澀

如何生成逼真的數據

mockjs 是一個不錯的數據生成工具, mockm 默認集成了它, 下面用它生成一批用戶信息.

module.exports = util => {
  return {
    db: {
      'users': util.libObj.mockjs.mock({
        'data|15-23': [ // 隨機生成 15 至 23 條數據
          {
            'id|+1': 1, // id 從 1 開始自增
            name: `@cname`, // 隨機生成中文名字
            'sex|1': [`男`, `女`, `保密`], // 性別從這三個選項中隨機選擇一個
          },
        ]
      }).data,
    },
  }
}

現在訪問 http://localhost:9000/users 已經可以看到很多逼真的用戶數據了.

如何更改后端返回的數據

很多時候后端不方便直接修改數據, 因為會涉及很多邏輯, 前端直接寫在代碼里既麻煩又容易引發問題.

假設后台接口 http://192.168.1.18:8080/api/user get 請求返回的數據是這樣的:

{
    "code": 200,
    "data": {
        "books": [
            {
                "page": 52,
                "type": "css"
            },
            {
                "page": 26,
                "type": "js"
            }
        ],
        "name": "張三"
    },
    "success": true
}

如果要修改 books 索引為 1 的 type 為 html, 那么配置如下:

module.exports = {
  proxy: {
    '/': `http://192.168.1.18:8080`,
    '/api/user': [`data.books[1].type`, `html`], // 數組第一個參數是修改的路徑, 第二個參數是修改后的值
  },
}

如果要直接替換整個返回值為 html , 可以這樣:

module.exports = {
  proxy: {
    '/': `http://192.168.1.18:8080`,
    '/api/user': [`html`], // 如果只提供一個參數, 則直接替換
  },
}

更多操作方式請參考 config.proxy

如何延遲后端接口的響應時間

示例延遲 http://192.168.1.18:8080/api/user 這個接口的響應時間為 5 秒之后:

module.exports = {
  proxy: {
    '/': `http://192.168.1.18:8080`,
    '/api/user': {
        mid (req, res, next) {
          setTimeout(next, 5000)
        },
    },
  },
}

如何創建一個下載文件的接口

實現一個文件下載接口 http://127.0.0.1:9000/file, 發送某文件給客戶端.

module.exports = {
  api: {
    '/file' (req, res, next) {
      res.sendFile(`這里寫要下載的文件路徑`)
    },
  },
}

如何創建 websocket 接口

實現一個 websocket 接口 ws://127.0.0.1:9000/wsecho, 當連接成功時發送 連接成功, 並把客戶端發送的信息再原樣返回給客戶端.

api: {
  'ws /wsecho' (ws, req) {
    ws.send(`連接成功`)
    ws.on('message', (msg) => {
      ws.send(msg)
    })
  }
},

客戶端連接代碼, 可以直接打開瀏覽器 console 測試:

function startWs(wsLink){
  window.ws = new WebSocket(wsLink)
  ws.onopen = (evt) => { 
    ws.send(`客戶端發送的消息`)
  }
  ws.onmessage = (evt) => {
    console.log( `服務器返回的消息`, evt.data)
  }
  ws.onclose = (evt) => { // 斷線重連
    setTimeout(() => startWs(wsLink), 1000)
  }
}
startWs(`ws://127.0.0.1:9000/wsecho`)
// ws.send(`發送新消息`)

如何接收客戶端上傳的文件

實現一個 post 方法的文件上傳接口 http://127.0.0.1:9000/file/upload, 文件上傳后保存到臨時目錄, 並返回文件信息.

module.exports = util => {
  const {
    toolObj,
  } = util
  return {
    api: {
      async 'post /file/upload' (req, res, next) {
        const multiparty = await toolObj.generate.initPackge(`multiparty`)
        const form = new multiparty.Form()
        form.parse(req, (err, fields = [], files) => {
          const data = {fields, files, err}
          res.json(data) // 保存上傳的文件並返回文件信息
        })
      },
    }
  }
}

如何實現動態的接口路徑參數

實現一個接口 http://127.0.0.1:9000/status/code, 其中 code 的位置是一個動態參數, 並返回接收到的 code.

module.exports = {
  api: {
    '/status/:code' (req, res, next) {
      const {params, query, body} = req
      res.json({statusCode: params.code})
    },
  },
}

如何向后端展示接口參數

告別截圖, 告別一問一答, 告別參數太多無法復制

默認情況下, 每次請求會生成一條鏈接在響應頭中的 x-test-api 上, 把這個鏈接發給后端即可.

• 方法1
  直接在啟動 mockm 的命令行里可能看到.

• 方法2
  在 http://127.0.0.1:9005 頁面上的列表中查找.

• 方法3
  如果你使用 chrome 開發工具, 可以在 Network 中找到請求的接口在 Response Headers 中找到 x-test-api.

如何遠程使用接口

把 config.remote 設置為 true 就能擁有域名的和 https 證書的公網接口, 能夠在微信公眾號上使用, 或者發給其他人遠程使用..

在控制台會顯示 遠程服務信息, x-test-api 和接口都會生成對應的遠程訪問鏈接.

如何接入微信消息推送

當 remote 設置為 true 后會獲得一個遠程地址, 將其帶上接口 /msg 填入 URL(服務器地址) 中, token 填寫例如 123, 數據格式推薦 JSON. 保存后即可驗證通過, 所有微信小程序的消息都會通過 /msg 這個接口收到.

module.exports = {
  remote: true,
  api: {
    '/msg' (req, res) {
      const token = `123` // 這里填寫 Token(令牌)
      const crypto = require(`crypto`)
      const { signature, timestamp, nonce, echostr, } = req.query
      const sha = crypto.createHash('sha1').update([token, timestamp, nonce].sort().join('')).digest('hex')
      sha === signature ? res.send(echostr) : res.json({ msg: `驗證失敗` })
      console.log(req.query, req.body)
    },
  },
}

如何恢復出錯的接口

如果某個接口之前是好的, 但是由於某些問題現在壞了, 后端又沒來得及修復, 可是前端現在有頁面依賴這個接口, 怎么辦?

在 http://127.0.0.1:9005 頁面選擇對應接口的請求歷史, 點擊 webApi => 使用此記錄 即可.

如何在后端關閉時不影響頁面

頁面要展示的內容來源於數據, 如果后端服務器出現問題, 所有接口無法使用, 這時候修改請求地址為 http://127.0.0.1:9001 即可讓頁面使用之前服務器返回的數據.

如何使用多個主機不同的接口

如果某個項目需要用到兩個接口, 例如分別在 192.168.1.13:8098 和 192.168.1.13:8099, 啟動多個 mm 實例即可.

如果想要使用同一份配置文件, 只是接口地址不同, 那么只需要從命令行傳入不同的部分即可:

mm dataDir=./httpData/8081/ port=8081 replayPort=8181  testPort=8281 proxy=http://192.168.1.13:8081
mm dataDir=./httpData/8082/ port=8082 replayPort=8182  testPort=8282 proxy=http://192.168.1.13:8082

如果要使用不同的配置, 那么啟動 mm 時傳入配置文件路徑即可, 然后再從配置文件中編寫不同的部分:

mm config=./8081.config.js
mm config=./8082.config.js

寄語

如果有任何使用問題, 請直接問我, 必將盡力解決.

如果覺得有用, 開源不易, 點個 start 以表支持:

• 源碼地址: https://github.com/wll8/mockm
• 文檔地址: https://hongqiye.com/doc/mockm

​