完整的Axios封装-单独API管理层、取消重复请求、Loading、状态码...

项目地址

https://github.com/ChinaJiu/axios-encapsulation

准备工作

前端

vite + vue3

npm init @vitejs/app

npm install axios

后端

借用node自个搭建一个简单的服务器，具体看源码

独立的API管理层

做好以上准备工作后，我们就可以开始进入正题了。一个项目的所有API接口统一管理是非常重要的，这样便于后期的更新维护，为此我们单独划分出API层来管理项目的所有API，以模块来划分每个API归属的文件。

我们在项目中创建 api文件夹 用来管理所有的API，创建 axios.js 文件二次封装axios，其他文件就是对应项目中的功能模块，如所有商品相关的API就放在 goods.js 文件，这样子就很有条理性。

一、我们先来简单的编写 axios.js。

import axios from 'axios';

function myAxios(config) {
const service = axios.create({
    baseURL: 'http://127.0.0.1:3000',
    timeout: 3000
  })

  return service(config)
}

export default myAxios;

需要注意的是 service(config) 返回的是一个Promise对象哦。 (上面之所以设计成一个函数是为了后续的一些封装操作，之后会讲到)

二、下面我们来 goods.js 中编写获取商品列表的API。

import myAxios from './axios'

export function getListApi(param) {
  return myAxios({
    url: '/api/list',
    method: 'get',
    data: param
  }
}

三、最后我们在页面中具体使用，在 App.vue 文件中随便加一个按钮，点击触发请求。

<template>
  <button @click="getList">点击</button>
</template>

<script lang='ts'>
import {defineComponent} from 'vue'
import {getListAPI} from '@/api/goods.js';
export default defineComponent({
  setup() { 
    function getList() {
      getListAPI().then(res => {
        console.log(res)
      })
    }

    return {
      getList
    }
  }
})
</script>

到此我们就简单的划分出API管理层了，每次我们新增加一个API，只需要找到对应模块的API文件添加，在具体页面导入使用就行了。

可以用 xxxAPI 结尾来标记为API方法以防和普通方法混合(^ω^)！！！可能很多人觉得这样子每次都需要导入很麻烦，现在网上有很多做法就是直接将所有的API都挂载在Vue的实例上，直接通过 this.$axios.getList() 这样子去使用，个人感觉这确实挺方便的，适合项目小、API比较少的情况，要是项目比较庞大，里面需要的API比较多，就容易开始混淆，不好分类API，利用this也要考虑this指向问题，Vue3 更是没有所谓的this。

取消重复请求

说起这个重复请求，感觉用到得比较少，心理总有怎么一种想法就算多请求一次又能怎么样，服务器会塌吗？页面会挂吗？明显不会嘛，不要大惊小怪，哈哈哈。再说没事怎么会多发重复的请求呢？不可能的。

而且做取消重复请求操作，其实取消后的请求还是有可能会到达了后端，只是前端浏览器不处理而已，但是呢，哎，我们还是得做做工作，不，非做不可，所谓以防万一，严谨，程序猿需要严谨！！！发生重复请求的场景一般有这两个：

快速连续点击一个按钮，如果这个按钮未进行控制，就会发出重复请求，假设该请求是生成订单，那么就有产生两张订单了，这是件可怕的事情。当然一般前端会对这个按钮进行状态处理控制，后端也会有一些幂等控制处理策略啥的，这是个假设场景，但也可能会发生的场景。
对于列表数据，可能有tab状态栏的频繁切换查询，如果请求响应很慢，也会产生重复请求。当然现在很多列表都会做缓存，如Vue中用 <keep-alive />。

如何取消一个已发送的请求

在开始正题前，我们要先来了解一下，如何取消一个已发送的请求，不知道铁汁们对JS中的 XMLHttpRequest 对象是否了解？(不知道也当你知道了) 你只要知道axios底层就是依赖于它的就行，也就是它的二次封装，那我们对axios再次封装，也就是三次封装？套娃？

XMLHttpRequest 对象是我们发起一个网络请求的根本，在它底下有怎么一个方法 .abort()，就是中断一个已被发出的请求。

那么axios自然也有对其的相关封装，就是 CancelToken，文档上介绍的用法：

var CancelToken = axios.CancelToken;
var cancel;

axios.get('/user/12345', {
  cancelToken: new CancelToken(function executor(c) {
    // executor 函数接收一个 cancel 函数作为参数
    cancel = c;
  })
});

// 取消请求
cancel();

简单理解就是通过 new axios.CancelToken()给每个请求带上一个专属的CancelToken，之后会接收到一个cancel() 取消方法，用于后续的取消动作，所以我们需要对应的存储好这个方法。

开始正题

通过上面的了解，下面就能进入正题部分了，接下来我们大致整体思路就是收集正在请求中的接口，也就是接口状态还是pending状态的，让他们形成队列储存起来。如果相同接口再次被触发，则直接取消正在请求中的接口并从队列中删除，再重新发起请求并储存进队列中；如果接口返回结果，就从队列中删除，以此过程来操作。

判断重复请求并储存进队列

首先我们要收集请求中的接口并判断哪些请求是重复请求，我们才能取消它，那么如何判断呢？很简单，只要是请求地址、请求方式、请求参数一样，那么我们就能认为是一样的。而我们要存储的队列里面的数据结构很明显应该是以键值对的形式来存储，这里面我们选择 Map 对象来操作。

// axios.js
const pendingMap = new Map();

/**
 * 生成每个请求唯一的键
 * @param {*} config 
 * @returns string
 */
function getPendingKey(config) {
  let {url, method, params, data} = config;
  if(typeof data === 'string') data = JSON.parse(data); // response里面返回的config.data是个字符串对象
  return [url, method, JSON.stringify(params), JSON.stringify(data)].join('&');
}

/**
 * 储存每个请求唯一值, 也就是cancel()方法, 用于取消请求
 * @param {*} config 
 */
function addPending(config) {
  const pendingKey = getPendingKey(config);
  config.cancelToken = config.cancelToken || new axios.CancelToken((cancel) => {
    if (!pendingMap.has(pendingKey)) {
      pendingMap.set(pendingKey, cancel);
    }
  });
}

取消重复请求并出删除队列

// axios.js
/**
 * 删除重复的请求
 * @param {*} config 
 */
function removePending(config) {
  const pendingKey = getPendingKey(config);
  if (pendingMap.has(pendingKey)) {
     const cancelToken = pendingMap.get(pendingKey);
     cancelToken(pendingKey);
     pendingMap.delete(pendingKey);
  }
}

添加拦截器

// axios.js
function myAxios(axiosConfig) {
  const service = axios.create({
    baseURL: 'http://localhost:8888', // 设置统一的请求前缀
    timeout: 10000, // 设置统一的超时时长
  });

  service.interceptors.request.use(
    config => {
      removePending(config);
      addPending(config);
      return config;
    }, 
    error => {
      return Promise.reject(error);
    }
  );

  service.interceptors.response.use(
    response => {
      removePending(response.config);
      return response;
    },
    error => {
      error.config && removePending(error.config);
      return Promise.reject(error);
    }
  );

  return service(axiosConfig)
}

我们在上面提到的 getList() 方法里面简单模拟连续发出了三次重复请求，然后把浏览器设置成3G模式，就能看到效果啦。

// App.vue
function getList() {
  getListAPI().then(res => {console.log(res)})
  setTimeout(() => {
    getListAPI().then(res => {console.log(res)})
  }, 200);
  setTimeout(() => {
    getListAPI().then(res => {console.log(res)})
  }, 400);
}

需要注意，上面说了取消正在请求中的接口，说明这接口有可能已经到达后端了，只是后端响应慢，所以如果你的接口响应比较快的话，就很难看到效果；如果你是自己搭建的服务，只要通过接口返回时延时下就可以看到效果；又或者通过浏览器的network调整网络速度也可以哦。

对于取消后的请求我们也应该有个合理的处理，不能就不管了，尽可能的达到代码可控的底部，它会被归类到异常里面，下面会说到(^ω^)。

配置化

之所以弄成配置化取消重复请求，是因为可能存在一些特殊变态的场景情况，是需要重复请求，如输入实时搜索、实时更新数据等，反正就是可能存在吧。(￣y▽￣)~*

// axios.js
function myAxios(config, customOptions) {
  const service = axios.create({
    baseURL: 'http://127.0.0.1:3000', // 设置统一的请求前缀
    timeout: 10000, // 设置统一的超时时长
  });

  // 自定义配置
  let custom_options = Object.assign({
    repeat_request_cancel: true, // 是否开启取消重复请求, 默认为 true
  }, customOptions);

  service.interceptors.request.use(
    config => {
      removePending(config);
      custom_options.repeat_request_cancel && addPending(config);
      return config;
    }, 
    error => {
      return Promise.reject(error);
    }
  );
  ...
}

我们在上面增加了一个自定义配置的参数，现在每个API方法就能拥有两个参数，第一个参数传递的是axios原本的一些配置，第二个参数就是我们自己的一些自定义参数了，如我们定义 repeat_request_cancel 来控制是否开启取消重复请求的功能。后续更多功能，我们也能添加进其中，相当于可定制化每个API方法，是不是很棒！！！

// goods.js
export function getListAPI(paramsList) {
  return myAxios({
    url: '/api/list',
    method: 'get',
    params: paramsList
  }, {
    repeat_request_cancel: false
  })
}

Loading

异步数据是非常常见的场景，一个良好的Loading效果能很好的加强用户体验，也能让我们回避一些问题，如上面提到的重复请求，如果在发起了一个请求后立即就出现一个Loading层，那么用户就无法再次点击而造成重复多次请求了。添加怎么一个功能我们需要考虑怎么三件事：

同一时间内发起多个请求，我们只需要展示一个Loading层即可，不需要产生多个造成重复展示。
同一时间内发起多个请求展示的Loading层以最后一个请求响应而关闭销毁。
此功能依旧要进行可配置化处理。

废话不多说，我们直接以 ElementPlus 的Loading效果玩耍，具体查看代码相关注释。

// axios.js
const LoadingInstance = {
  _target: null, // 保存Loading实例
  _count: 0
};

function myAxios(config, customOptions) {
  const service = axios.create({
    baseURL: 'http://localhost:3000', // 设置统一的请求前缀
    timeout: 10000, // 设置统一的超时时长
  });

  // 自定义配置
  let custom_options = Object.assign({
    repeat_request_cancel: true, // 是否开启取消重复请求, 默认为 true
    loading: false, // 是否开启loading层效果, 默认为false
  }, customOptions);


  service.interceptors.request.use(
    config => {
      removePending(config);
      custom_options.repeat_request_cancel && addPending(config); 
      // 创建loading实例  
      if (custom_options.loading) {
        LoadingInstance._count++;
        if(LoadingInstance._count === 1) {
          LoadingInstance._target = ElLoading.service();
        }
      }
      return config;
    }, 
    error => {
      return Promise.reject(error);
    }
  );

  service.interceptors.response.use(
    response => {
      removePending(response.config);
      custom_options.loading && closeLoading(custom_options); // 关闭loading
      return response;
    },
    error => {
      error.config && removePending(error.config);
      custom_options.loading && closeLoading(custom_options); // 关闭loading
      return Promise.reject(error);
    }
  );

  return service(config)
}

/**
 * 关闭Loading层实例
 * @param {*} _options 
 */
function closeLoading(_options) {
  if(_options.loading && LoadingInstance._count > 0) LoadingInstance._count--;
  if(LoadingInstance._count === 0) {
    LoadingInstance._target.close();
    LoadingInstance._target = null;
  }
}

我们也能自定义处理掉，考虑到简洁单一点我们直接增加第三个参数。

// axios.js
function myAxios(axiosConfig, customOptions, loadingOptions) {
  service.interceptors.request.use(
    config => {
      ...
      // 创建loading实例
      if (custom_options.loading) {
        LoadingInstance._count++;
        if(LoadingInstance._count === 1) {
          LoadingInstance._target = ElLoading.service(loadingOptions);
        }
      }
      return config;
    }, 
    ...
  );
  ...  
}

至此，我们就能给每个需要页面级Loading层的API方法定制不同的Loading层了。

// goods.js
export function getListAPI(paramsList) {
  return myAxios({
    url: '/api/list',
    method: 'get',
    params: paramsList
  }, {
    loading: true
  }, {
    text: '获取列表数据....'
  })
}

判断不同HTTP状态码

一个良好展示接口实时状态的提示信息是非常重要的，开发时方便前端人员定位问题，测试时方便测试人员通知对应人员，在一些复杂特殊场景给予用户提示引导。

在上正式代码前，我们先打印几种接口异常情况，测试代码如下：

// axios.js
function myAxios(axiosConfig, customOptions, loadingOptions) {
  ...
  service.interceptors.response.use(
    ...
    error => {
      ...
      httpErrorStatusHandle(error); // 处理错误状态码
      return Promise.reject(error); // 错误继续返回给到具体页面
    }
  );
  ...
}

/**
 * 处理异常
 * @param {*} error 
 */
function httpErrorStatusHandle(error) {
  console.log('error: ', error);
  console.log('error.message: ', error.message);
  console.log('error.response: ', error.response);
}

具体编码

// axios.js
/**
 * 处理异常
 * @param {*} error 
 */
function httpErrorStatusHandle(error) {
  // 处理被取消的请求
  if(axios.isCancel(error)) return console.error('请求的重复请求：' + error.message);
  let message = '';
  if (error && error.response) {
    switch(error.response.status) {
      case 302: message = '接口重定向了！';break;
      case 400: message = '参数不正确！';break;
      case 401: message = '您未登录，或者登录已经超时，请先登录！';break;
      case 403: message = '您没有权限操作！'; break;
      case 404: message = `请求地址出错: ${error.response.config.url}`; break; // 在正确域名下
      case 408: message = '请求超时！'; break;
      case 409: message = '系统已存在相同数据！'; break;
      case 500: message = '服务器内部错误！'; break;
      case 501: message = '服务未实现！'; break;
      case 502: message = '网关错误！'; break;
      case 503: message = '服务不可用！'; break;
      case 504: message = '服务暂时无法访问，请稍后再试！'; break;
      case 505: message = 'HTTP版本不受支持！'; break;
      default: message = '异常问题，请联系管理员！'; break
    }
  }
  if (error.message.includes('timeout')) message = '网络请求超时！';
  if (error.message.includes('Network')) message = window.navigator.onLine ? '服务端异常！' : '您断网了！';

  ElMessage({
    type: 'error',
    message
  })
}

编写这个处理异常的方法其实不难，但我们注意要处理一下上面讲过的取消重复请求的情况，取消后的请求也会进入这其中，我们简单的将重复请求的接口打印在控制台即可。我们借助ElementPlus的Message组件来提示信息，具体提示文案可以自行更改或添加更多情况，也能用接口来定义这些信息，就看具体情况啦。当然也我们把该功能配置化：

// axios.js
function myAxios(axiosConfig, customOptions, loadingOptions) {
  ...
  // 自定义配置
  let custom_options = Object.assign({
    ...
    error_message_show: true, // 是否开启接口错误信息展示，默认为true
  }, customOptions);
 
  service.interceptors.response.use(
    ...
    error => {
      ...
      custom_options.error_message_show && httpErrorStatusHandle(error); // 处理错误状态码
      return Promise.reject(error); // 错误继续返回给到具体页面
    }
  );
  ...
}

至此，本篇文章就写完啦，撒花撒花。