axios-ex

A integration solution of axios for large enterprise projects. Support request concurrency control & cancel requests & automatic retry & requests times limit, etc.

Documentation • Change Log

Read this in other languages: English | 简体中文

Installation

axios-ex comes with the latest version of axios, so you can install it without the axios package

# use pnpm
$ pnpm install axios-ex

# use npm
$ npm install axios-ex --save

# use yarn
$ yarn add axios-ex

Usage

General use

// {app_root}/src/plugins/axios.js
import { getCookie, setCookie } from 'js-cool'
import AxiosExtend from 'axios-ex'

/**
 * Set the request header
 *
 * @param {object} instance AxiosInstance
 */
function setHeaders(instance) {
  instance.defaults.headers.post['Content-Type'] = 'application/x-www-form-urlencoded'
}
/**
 * Request Interceptor
 *
 * @param {object} config AxiosRequestConfig
 * @param {object} options request options AxiosExtendRequestOptions
 * @returns AxiosRequestConfig
 */
function onRequest(config, options = {}) {
  // some codes
  return config
}
/**
 * Execute on request error
 *
 * @param {object} err Error
 */
function onRequestError(err) {
  console.error(err)
}
/**
 * Response Interceptor
 *
 * @param {object} res AxiosResponse<any>
 * @param {object} options request options AxiosExtendRequestOptions
 * @returns Promise<unknown>
 */
function onResponse(res, options = {}) {
  if (res.data.success) return res.data
  return Promise.reject(res.data)
}
/**
 * Execute in response error
 *
 * @param {object} err Error
 */
function onResponseError(err) {
  console.error(err)
}
/**
 * Execute on request error & response error
 *
 * @param {object} err Error
 */
function onError(err) {
  console.error(err)
}
/**
 * Request Cancelled
 *
 * @param {object} err Error
 */
function onCancel(err) {
  console.error(err.message)
}

// Instantiation
const axiosEx = new AxiosExtend({
  unique: true, // Whether to cancel the previous similar requests, default: false
  retries: 0, // Number of retries, default: 0, no retries
  orderly: false, // Whether to return in order, default: true
  setHeaders, // function for setting request headers
  onRequest, // Request Interceptor
  onRequestError, // Execute on request error
  onResponse, // Response Interceptor
  onResponseError, // Execute on response error
  onError, // Execute on request error & response error
  onCancel // Callback when request is cancelled
})

export default options => {
  // Here set the unique and orderly priority higher than the instantiation configuration
  options.unique = options.unique ?? false
  options.orderly = options.orderly ?? false
  // Here the unique has a higher priority
  return axiosEx.create(options)
}

Define the delay function for failed retries

1. Customize the retry delay time

   // Configuration when instantiating
   const axiosEx = new AxiosExtend({
     // ...
     retryDelay: retryCount => {
       return retryCount * 1000
     }
     // ...
   })

2. Or use axios-ex built-in function, exponentialDelay randomly incremented by 0%-50%

   import AxiosExtend, { exponentialDelay } from 'axios-ex'
   // Configuration when instantiating
   const axiosEx = new AxiosExtend({
     // ...
     retryDelay: exponentialDelay
     // ...
   })

Using with vue2.0

Sometimes we need to use this (vue instance) inside onRequest or onResponse, we can use it like this

import AxiosExtend from 'axios-ex'

let axiosEx = null
// Request Interceptor
function onRequest(config, options = {}) {
  // this => vueInstance
  return config
}
// Response Interceptor
function onResponse(res, options = {}) {
  // hide loading
  if (this instanceof Vue) {
    this.$loader.hide()
  }
  if (res.data.success) return res.data
  return Promise.reject(res.data)
}

export default options => {
  // Only need to initialize once
  if (!axiosEx)
    axiosEx = new AxiosExtend({
      onRequest: onRequest.bind(this),
      onResponse: onResponse.bind(this)
    })

  // show loading
  if (this instanceof Vue) {
    this.$loader.show()
  }
  return axiosEx.create(options)
}

Using unpkg CDN

<script src="https://unpkg.com/axios-ex@2.4.0/dist/index.global.prod.js"></script>

Support & Issues

Please open an issue here.

License

MIT