api-mock-handler

基于 axios 和 mockjs 的 API 控制工具.

Usage no npm install needed!

<script type="module">
  import apiMockHandler from 'https://cdn.skypack.dev/api-mock-handler';
</script>

README

AMH

基于 axiosmockjs 的 API 控制工具.

功能

  • 基于 API 定义生成请求代理.
  • 提供全局、命名空间、接口三种层级的 mock 控制.
  • 允许自定义所使用的请求库,默认为 axios.
  • 允许为请求自定义发起方法.

安装

使用 npm:

$ npm install api-mock-handler

使用

创建实例

import amh from 'api-mock-handler'

const instance = amh.create({
    interface: {
        user: {
            mock: true,
            baseURL: '/api/user',
            login: {
                url: '/login',
                method: 'post'
            },
            logout: {mock: false}
        }
    },
    mock: true,
    mocker: {
        user: {
            login ({body}) {
                // this 指向 mockjs 实例
                const {username} = JSON.parse(body)
                return {code: 200, msg: '', data: {username}}
            }
        }
    }
})

此时 instance 将会代理如下两个接口:

[{
    url: '/api/user/login',
    method: 'post',
    mock: true
  }, {
    url: '/api/user/logout',
    method: 'get',
    mock: false
  }]

调用接口

instance.user.login({
    data: {username: 'admin'}
}).then(res => res.data)
    .then(data => {
    console.dir(data)
})

// {code: 200, msg: '', data: {username: 'admin'}}

instance.user.logout()
 .catch(error => console.error(error))
// 

该接口将会被 mock ,而模拟数据的产生由 mocker.user.login 函数定义。

创建实例的参数

{
    interfaces: object, // 必填
    mock: boolean, // 选填,默认为 false,
    mocker: object, // 选填,当 mock 为 true 时必填
    requester: function, // 选填,请求发起库,默认为 axios
    onRequest: function, // 选填
    concatPath: function, // 选填,定义路径解析行为
    debug: boolen, // 选填,默认为 false
}
  • interfaces 接口列表,由全局 baseURL 与一组命名空间组成:

    {
        baseURL: string, // 选填,作为域名部分与后面接口路径进行拼接
        [...namespace]
    }
    

    命名空间,由 baseURLmock与一组接口组成:

    {
        baseURL: string, // 选填,默认为命名空间的名字,与接口路径进行拼接
        mock: boolean, // 选填,默认为 false,当设为 true 时,此命名空间下的所有 mock 属性未被显式设为 false 的接口都将打开 mock 开关
        [...interface]
    }
    

    接口,组成:

    {
        url: string, // 选填,默认为接口的名字
        mock: boolean, // 选填,默认为 false,接口是否需要 mock 以此属性的显式设置值为准
        method: string, // 选填,接口的请求方式,默认为 get
        meta: object, // 选填,接口的一些元信息
    }
    
  • mock 用于声明是否开启 mock 功能。

  • mocker 若某个命名空间中某个接口设置了 mock 参数为 true,则需要在此参数中设置同命名空间、同接口名的处理函数,否则会报错。

  • requester 发起请求的请求库,默认为 axios。

  • onRequest 定义如何发起请求,函数签名为:

    (config, args, requester) => {}
    

    对于调用(下称 call):

    instance.user.login({data: {username: 'admin'}})
    

    onRequest 函数响应如下:

    (config, args, requester) => {
        /**
         * config: {
         *   url: '/api/user/login',
         *   method: 'post',
         *   meta: {}
         * }
         * 
         * args: [{
         *   data: {username: 'admin'}
         * }]
         *
         * requester: axios (未设置 requester 的情况下)
         */
        return {} // 此函数返回结果即为 call 的返回结果
    }
    
  • concatPath 默认的路径拼接行为:

    (baseURL, url) => url[0] === '/' ? `${baseURL}${url}` : `${baseURL}/${url}`
    
  • debug 开启后,将会在以下情形输出一些信息:

    • 没有为命名空间设置 baseURL

      Warn: The namespace [${namespace}] does not set baseURL!
      
    • 提示你为某个命名空间打开了 mock 开关

      Info: You turned on the mock option for the namespace [${namespace}]
      
    • 成功为某个接口绑定了 mock 处理函数

      Info: Bind the mock function for interface [${namespace}.${_interface_name_}]
      

当发生以下情况时将会报错:

  • 开启了全局 mock 却未提供 mocker

    You have enabled mock mode but don't provide mocker.
    
  • 为某个接口开启了 mock 却没有在 mocker 中提供相应的处理函数

    You turned on the mock option for interface [${namespace}.${_interface_name_}] but did not provide the corresponding handler in the mocker.
    
  • 当你尝试使用一个不存在的命名空间时

    The definition of namespace [${namespace}] could not be found.
    
  • 当你尝试使用一个不存在的接口时

    The definition of interface [${namespace}.${_interface_name_}] could not be found.
    

注意事项

关于 Mockjs

  • 此工具的 mock 功能由 mockjs 实现,因此请不要在项目中自行引入 mockjs,否则会导致 mockjs 重复创建 xhr 的代理,导致死循环。

  • 可以通过 amh.Mock 获取 mockjs 实例。