大文件上传

# 告别臃肿 Axios 封装！打造 Vue 风格插件化请求管理工具


## 📘 前言
在前端项目开发中，Axios 几乎是标配 HTTP 请求库。
为了实现鉴权、日志、错误处理、重复请求取消、接口重试、缓存等能力，我们几乎都会对 Axios 进行二次封装。

但传统封装普遍存在这些痛点：
- 所有逻辑耦合在一个文件，代码臃肿
- 新增/删除功能要改多处，维护成本高
- 功能混杂，可读性差
- 无法灵活组合能力，复用性差

今天给大家带来一套**模仿 Vue 插件机制的 Axios 插件化封装**：
`createAxios().use(插件1).use(插件2)`
真正做到：解耦、可插拔、高复用、易维护、生产可用。




---

## 🎯 设计目标
- 模仿 Vue 插件机制，使用 `.use()` 链式调用
- 每个功能独立成插件，互不影响
- 支持插件配置、防重复安装、异常捕获
- 内置高频通用插件，开箱即用
- 支持预设模式，一行创建完整请求实例

---

## 📁 目录
1. 核心实现：createAxios 插件管理器
2. 插件编写规范
3. 内置七大实用插件
4. 使用示例（链式调用）
5. 预设模式（极简/默认/全量）
6. 完整源码（可直接复制使用）

---

## 🔧 一、核心实现：createAxios 插件管理器
这是整个架构的灵魂，负责创建 Axios 实例、管理插件生命周期。

```javascript
import axios from 'axios';

export function createAxios(config = {}) {
  const instance = axios.create(config);
  const installedPlugins = new Set();
  const pluginOrder = [];

  function use(plugin, options = {}) {
    if (typeof plugin === 'function') {
      plugin = { install: plugin };
    }

    if (!plugin || typeof plugin.install !== 'function') {
      console.error('[AxiosUse] 插件必须提供 install 方法');
      return instance;
    }

    if (installedPlugins.has(plugin)) {
      console.warn('[AxiosUse] 插件已安装，跳过');
      return instance;
    }

    installedPlugins.add(plugin);
    try {
      plugin.install(instance, options);
      console.log(`[AxiosUse] ✅ 插件安装成功: ${plugin.name || 'anonymous'}`);
    } catch (error) {
      console.error('[AxiosUse] ❌ 插件安装失败', error);
    }

    return instance;
  }

  function useBatch(plugins) {
    plugins.forEach(({ plugin, options = {} }) => {
      use(plugin, options);
    });
    return instance;
  }

  instance.use = use;
  instance.useBatch = useBatch;
  instance.getInstalledPlugins = () => [...pluginOrder];
  instance.hasPlugin = (plugin) => installedPlugins.has(plugin);

  return instance;
}
```

## 📝 二、插件编写规范

和 Vue 插件完全一致，必须提供 install 方法。
```
const MyPlugin = {
  name: 'MyPlugin',
  install(axiosInstance, options) {
    axiosInstance.interceptors.request.use(config => {
      return config;
    });
  }
};

const http = createAxios().use(MyPlugin);
```

## 🧩 三、内置七大实用插件

1. LogPlugin
请求 / 响应 / 错误 / 耗时日志，开发调试神器
2. TokenPlugin
自动携带 Token，支持白名单、自定义请求头
3. CancelDuplicatePlugin
取消重复请求，防止重复点击、接口竞态
4. RetryPlugin
指数退避重试，弱网环境必备
5. LoadingPlugin
自动管理全局 Loading，计数模式防闪烁
6. CachePlugin
GET 请求缓存（LRU 策略），提升页面性能
7. ErrorHandlerPlugin
统一错误处理，状态码映射 + 全局提示

## 🚀 四、使用示例（链式调用）
```
const http = createAxios({ baseURL: '/api' })
  .use(LogPlugin)
  .use(TokenPlugin, {
    getToken: () => localStorage.getItem('token'),
    whiteList: ['/login', '/register']
  })
  .use(CancelDuplicatePlugin)
  .use(RetryPlugin, { maxRetries: 3 })
  .use(LoadingPlugin)
  .use(CachePlugin, { ttl: 5 * 60 * 1000 })
  .use(ErrorHandlerPlugin);
```

## ⚡️ 五、预设模式（一行创建实例）

```
import { createAxiosWithPreset } from '@/utils/axios';

// 极简模式
const httpMin = createAxiosWithPreset('minimal');

// 默认模式
const httpDefault = createAxiosWithPreset('default');

// 全量模式
const httpFull = createAxiosWithPreset('full');
```



## 📦 六、完整源码
```
/**
 * Axios 插件管理工具 - 类似 Vue 的 use 链式调用风格
 */

import axios from 'axios';

export function createAxios(config = {}) {
  const instance = axios.create(config);
  const installedPlugins = new Set();
  const pluginOrder = [];

  function use(plugin, options = {}) {
    if (typeof plugin === 'function') {
      plugin = { install: plugin };
    }

    if (!plugin || typeof plugin.install !== 'function') {
      console.error('[AxiosUse] 插件必须提供 install 方法:', plugin);
      return instance;
    }

    if (installedPlugins.has(plugin)) {
      console.warn('[AxiosUse] 插件已安装，跳过:', plugin.name || 'anonymous');
      return instance;
    }

    installedPlugins.add(plugin);
    const pluginInfo = {
      name: plugin.name || 'anonymous',
      options,
      installTime: Date.now()
    };
    pluginOrder.push(pluginInfo);

    try {
      plugin.install(instance, options);
      console.log(`[AxiosUse] ✅ 插件安装成功: ${pluginInfo.name}`);
    } catch (error) {
      console.error(`[AxiosUse] ❌ 插件安装失败: ${pluginInfo.name}`, error);
    }

    return instance;
  }

  function useBatch(plugins) {
    plugins.forEach(({ plugin, options = {} }) => {
      use(plugin, options);
    });
    return instance;
  }

  instance.use = use;
  instance.useBatch = useBatch;
  instance.getInstalledPlugins = () => [...pluginOrder];
  instance.hasPlugin = (plugin) => installedPlugins.has(plugin);

  return instance;
}

// ==================== 内置插件 ====================

export const LogPlugin = {
  name: 'LogPlugin',
  install(instance, options = {}) {
    const {
      logRequest = true,
      logResponse = true,
      logError = true,
      prefix = '[Axios]'
    } = options;

    instance.interceptors.request.use(
      (config) => {
        config._startTime = Date.now();
        logRequest && console.log(`${prefix} 📤 ${config.method?.toUpperCase()} ${config.url}`);
        return config;
      },
      (error) => {
        logError && console.error(`${prefix} ❌ 请求错误:`, error.message);
        return Promise.reject(error);
      }
    );

    instance.interceptors.response.use(
      (response) => {
        const duration = Date.now() - response.config._startTime;
        logResponse && console.log(`${prefix} 📥 ${response.config.url} - ${response.status} (${duration}ms)`);
        return response;
      },
      (error) => {
        if (logError) {
          const duration = Date.now() - (error.config?._startTime || Date.now());
          console.error(
            `${prefix} ❌ ${error.config?.url} - ${error.response?.status || 'Network Error'} (${duration}ms)`
          );
        }
        return Promise.reject(error);
      }
    );
  }
};

export const TokenPlugin = {
  name: 'TokenPlugin',
  install(instance, options = {}) {
    const {
      getToken = () => localStorage.getItem('token'),
      headerName = 'Authorization',
      tokenPrefix = 'Bearer ',
      whiteList = []
    } = options;

    instance.interceptors.request.use(
      (config) => {
        if (whiteList.some(url => config.url?.includes(url))) {
          return config;
        }
        const token = getToken();
        if (token) {
          config.headers[headerName] = `${tokenPrefix}${token}`;
        }
        return config;
      },
      (error) => Promise.reject(error)
    );
  }
};

export const CancelDuplicatePlugin = {
  name: 'CancelDuplicatePlugin',
  install(instance, options = {}) {
    const {
      generateKey = (config) => `${config.method}_${config.url}_${JSON.stringify(config.params)}`,
      message = '取消重复请求'
    } = options;

    const pendingRequests = new Map();

    instance.interceptors.request.use(
      (config) => {
        const key = generateKey(config);
        if (pendingRequests.has(key)) {
          pendingRequests.get(key).cancel(message);
        }
        const source = axios.CancelToken.source();
        config.cancelToken = source.token;
        pendingRequests.set(key, source);
        config._cancelKey = key;
        return config;
      },
      (error) => Promise.reject(error)
    );

    instance.interceptors.response.use(
      (response) => {
        const key = response.config._cancelKey;
        if (key) pendingRequests.delete(key);
        return response;
      },
      (error) => {
        const key = error.config?._cancelKey;
        if (key) pendingRequests.delete(key);
        return Promise.reject(error);
      }
    );
  }
};

export const RetryPlugin = {
  name: 'RetryPlugin',
  install(instance, options = {}) {
    const {
      maxRetries = 3,
      retryDelay = 1000,
      retryDelayMultiplier = 2,
      maxRetryDelay = 30000,
      retryCondition = (error) => {
        return !error.response || error.response.status >= 500;
      }
    } = options;

    instance.interceptors.response.use(
      (response) => response,
      async (error) => {
        const config = error.config;
        if (!config) return Promise.reject(error);

        config._retryCount = config._retryCount || 0;

        if (config._retryCount >= maxRetries || !retryCondition(error)) {
          return Promise.reject(error);
        }

        config._retryCount++;
        const delay = Math.min(
          retryDelay * Math.pow(retryDelayMultiplier, config._retryCount - 1),
          maxRetryDelay
        );

        await new Promise(resolve => setTimeout(resolve, delay));
        return instance(config);
      }
    );
  }
};

export const LoadingPlugin = {
  name: 'LoadingPlugin',
  install(instance, options = {}) {
    const {
      showLoading = () => console.log('Loading...'),
      hideLoading = () => console.log('Loading done'),
      minDuration = 0
    } = options;

    let requestCount = 0;
    let minDurationTimer = null;

    instance.interceptors.request.use(
      (config) => {
        if (config.showLoading !== false) {
          if (requestCount === 0) {
            showLoading();
          }
          requestCount++;
        }
        config._showLoading = config.showLoading !== false;
        return config;
      },
      (error) => Promise.reject(error)
    );

    const hide = () => {
      requestCount--;
      if (requestCount <= 0) {
        requestCount = 0;
        if (minDuration > 0) {
          clearTimeout(minDurationTimer);
          minDurationTimer = setTimeout(() => {
            hideLoading();
          }, minDuration);
        } else {
          hideLoading();
        }
      }
    };

    instance.interceptors.response.use(
      (response) => {
        response.config._showLoading && hide();
        return response;
      },
      (error) => {
        error.config?._showLoading && hide();
        return Promise.reject(error);
      }
    );
  }
};

export const CachePlugin = {
  name: 'CachePlugin',
  install(instance, options = {}) {
    const {
      ttl = 5 * 60 * 1000,
      maxSize = 100,
      keyGenerator = (config) => `${config.url}_${JSON.stringify(config.params)}`
    } = options;

    const cache = new Map();
    const accessOrder = [];

    instance.interceptors.request.use(
      (config) => {
        if (config.method !== 'get' || config.cache === false) return config;
        const key = keyGenerator(config);
        const cached = cache.get(key);

        if (cached && Date.now() < cached.expireTime) {
          const source = axios.CancelToken.source();
          config.cancelToken = source.token;
          setTimeout(() => {
            source.cancel(JSON.stringify({ __fromCache: true, data: cached.data }));
          }, 0);
        }
        config._cacheKey = key;
        return config;
      },
      (error) => Promise.reject(error)
    );

    instance.interceptors.response.use(
      (response) => {
        const key = response.config._cacheKey;
        if (key && response.config.method === 'get') {
          if (cache.size >= maxSize) {
            const oldest = accessOrder.shift();
            cache.delete(oldest);
          }
          cache.set(key, {
            data: response.data,
            expireTime: Date.now() + ttl
          });
          accessOrder.push(key);
        }
        return response;
      },
      (error) => {
        if (axios.isCancel(error) && error.message) {
          try {
            const parsed = JSON.parse(error.message);
            if (parsed.__fromCache) {
              return Promise.resolve({
                data: parsed.data,
                config: error.config,
                status: 200,
                statusText: 'OK (from cache)',
                headers: {}
              });
            }
          } catch {}
        }
        return Promise.reject(error);
      }
    );
  }
};

export const ErrorHandlerPlugin = {
  name: 'ErrorHandlerPlugin',
  install(instance, options = {}) {
    const {
      handler = (error) => console.error('[ErrorHandler]', error.message),
      errorMap = {
        400: '请求参数错误',
        401: '未授权，请重新登录',
        403: '拒绝访问',
        404: '请求的资源不存在',
        500: '服务器内部错误',
        502: '网关错误',
        503: '服务不可用',
        504: '网关超时'
      }
    } = options;

    instance.interceptors.response.use(
      (response) => response,
      (error) => {
        if (error.response) {
          const status = error.response.status;
          error.message = errorMap[status] || `请求失败: ${status}`;
        } else if (error.request) {
          error.message = '网络错误，请检查网络连接';
        }
        handler(error);
        return Promise.reject(error);
      }
    );
  }
};

// ==================== 预设 ====================

export function createAxiosWithPreset(preset = 'default', config = {}) {
  const instance = createAxios(config);

  const presets = {
    minimal: [LogPlugin],
    default: [
      { plugin: LogPlugin },
      { plugin: TokenPlugin },
      { plugin: CancelDuplicatePlugin },
      { plugin: ErrorHandlerPlugin }
    ],
    full: [
      { plugin: LogPlugin },
      { plugin: TokenPlugin },
      { plugin: CancelDuplicatePlugin },
      { plugin: RetryPlugin, options: { maxRetries: 3 } },
      { plugin: LoadingPlugin },
      { plugin: CachePlugin },
      { plugin: ErrorHandlerPlugin }
    ]
  };

  (presets[preset] || presets.default).forEach(({ plugin, options }) => {
    instance.use(plugin, options);
  });

  return instance;
}

export default createAxios;
```

告别臃肿 Axios 封装！打造 Vue 风格插件化请求管理工具

Nginx Proxy Manager (NPM) 主要设计为反向代理工具，但可以通过 自定义Nginx配置 托管静态页面,具体步骤如下


# 1. Nginx Proxy Manager 安装
我们通过docker安装
docker-compose.yml
```
version: '3'
services:
  app:
    image: 'chishin/nginx-proxy-manager-zh:latest'
    restart: always
    ports:
      - '80:80'
      - '81:81'
      - '443:443'
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
```
通过如下命令启动
```sh
docker compose up -d
```

# 2. 如何托管静态站点

## 2.1 添加代理主机
- 登录 NPM 管理界面。
- 转到 Hosts → Proxy Hosts → Add Proxy Host.
- 在 Domain Names 中填写域名（或留空托管IP访问）。
- 其他设置留空（无需填写目标地址）。


![image.png](/static/img/04f19369fe4d5dbb2ff3df066b3dc06f.image.webp)

## 2.2 自定义nginx配置
切换到 Advanced 标签页，添加以下配置
```nginx
location / {
    root /var/www/mysite;  # 替换为你的静态文件目录
    index index.html;
    try_files $uri $uri/ /index.html; # 防止vue、react等spa但页面应用刷新404问题
}
```
注意上面的静态文件文件要替换成宿主机的目录，例如：`/data/website/meng-admin`

![image.png](/static/img/fbcca725a3561237c2d63759e4f0ed9a.image.webp)

# 3. 其他配置
## 3.1 配置api接口反向代理
```nginx
# 处理以/ma/api开头的请求
location ^~ /ma/api {
    # 重写URL：去掉/ma，保留/api及后面的部分
    rewrite ^/ma(/.*)$ $1 break;

    # 代理到目标服务器
    proxy_pass http://x.x.x.x:xx; # 转发到目标地址

    # 以下为常见的代理设置，根据需要添加
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    
    # 如果目标服务器需要处理WebSocket，可以添加以下两行
    # proxy_http_version 1.1;
    # proxy_set_header Upgrade $http_upgrade;
    # proxy_set_header Connection "upgrade";
}
```

# 4. 开启gzip，示例配置如下
```nginx
# ======================
# GZIP 压缩配置（核心）
# ======================
gzip on;  # 启用 gzip 压缩
gzip_min_length 1k;  # 最小压缩文件大小（1KB以上才压缩）
gzip_comp_level 6;   # 压缩级别（1-9，6是较好的平衡点）
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;  # 压缩的文件类型
gzip_vary on;       # 根据客户端支持情况动态启用压缩
gzip_proxied any;   # 对所有代理请求启用压缩
gzip_buffers 16 8k; # 压缩缓冲区
gzip_http_version 1.1; # 启用压缩的最小 HTTP 版本


location / {
   root /data/website/meng-admin;
   index index.html;
    try_files $uri $uri/ /index.html;
autoindex on;
            gzip on;
}

location ^~ /vite.svg {
   root /data/website/meng-admin/;
}

location  ^~  /assets{
    alias /data/website/meng-admin/assets;
    index index.html;
autoindex on;

expires 30d;
    add_header Cache-Control "public, no-transform";

            # 启用 gzip 和 Brotli 压缩
    gzip_static on;  # 优先使用预压缩文件
    # brotli_static on;
    
    # 确保路径正确结尾
    # 注意：移除了try_files中的路径重写
    try_files $uri $uri/ =404;
}

# 处理以/ma/api开头的请求
location ^~ /ma/api {
    # 重写URL：去掉/ma，保留/api及后面的部分
    rewrite ^/ma(/.*)$ $1 break;

    # 代理到目标服务器
    proxy_pass http://x.x.x.x:xx;

    # 以下为常见的代理设置，根据需要添加
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

# 启用代理压缩
    proxy_set_header Accept-Encoding gzip;
    
    # 如果目标服务器需要处理WebSocket，可以添加以下两行
    # proxy_http_version 1.1;
    # proxy_set_header Upgrade $http_upgrade;
    # proxy_set_header Connection "upgrade";
}
```

Nginx Proxy Manager托管静态站点

async await 语法是`ES7`出现的，是基于ES6的 promise和generator实现的,那么js底层是如何实现的呢，让promise异步状态变为await的同步写法。


async/await 是建立在Promise之上的语法糖，它的底层实现原理是基于状态机的转换和生成器（Generator）函数。下面我将详细描述其工作原理。
1. 生成器函数（Generator）和迭代器（Iterator）
生成器函数可以暂停和恢复执行。当调用生成器函数时，它返回一个迭代器对象，通过调用迭代器的next()方法可以逐步执行生成器函数体。每次遇到yield关键字，函数就会暂停执行并返回一个值。

2. 将异步操作转化为同步写法
async/await 通过暂停和恢复执行来实现异步操作的同步写法。async函数本质上是一个生成器函数，但使用了async关键字标记。await后面的表达式会被包装成Promise。

3. 状态机的实现
编译器（如Babel）会将async函数转换成生成器函数的形式，然后使用一个状态机（通常由一个包装函数实现）来管理生成器的状态，自动执行迭代过程。

转换步骤：

假设有这样一个async函数：

```javascript
async function example() {
  const result = await someAsyncCall();
  console.log(result);
}
```
它会被转换成类似下面的生成器函数：

```javascript
function example() {
  return spawn(function* () {
    const result = yield someAsyncCall();
    console.log(result);
  });
}
```
这里的spawn函数就是一个自动执行器，它会管理生成器的状态，处理Promise的解析，并继续执行生成器直到结束。

4. 自动执行器（spawn函数）的实现
自动执行器的作用是管理生成器的状态，处理每个yield出来的Promise，并根据Promise的结果（成功或失败）决定是继续执行还是抛出错误。

一个简化的自动执行器可能如下：
```javascript
function spawn(generatorFunc) {
  return new Promise((resolve, reject) => {
    const generator = generatorFunc();
    const step = (key, arg) => {
      let result;
      try {
        result = generator[key](arg);
      } catch (error) {
        return reject(error);
      }
      const { value, done } = result;
      if (done) {
        return resolve(value);
      }
      // 确保返回一个Promise
      Promise.resolve(value).then(
        value => step('next', value),
        error => step('throw', error)
      );
    };
    step('next');
  });
}
```

步骤解析：

spawn函数返回一个Promise，这样调用者可以使用.then()和.catch()。

创建生成器对象generator。
定义一个step函数，用于控制生成器的执行。它根据状态（'next'或'throw'）调用生成器的相应方法（generator.next()或generator.throw()）。

在首次调用时，使用step('next')启动生成器。

每次执行生成器的next或throw方法，都会返回一个对象{ value, done }，其中value是yield后面的表达式的值（通常是一个Promise），done表示生成器是否已经结束。

如果生成器未结束（done为false），则等待Promise解析（使用Promise.resolve来确保它是一个Promise），然后根据解析结果：

- 若成功，则使用step('next', value)将解析后的值传给生成器，并继续下一步。
- 若失败，则使用step('throw', error)将错误抛出到生成器内部，可以被生成器内的try-catch捕获。

如果生成器结束（done为true），则解析外部的Promise（即整个async函数的Promise）为生成器函数返回的值（即return的值）。

5. 错误处理

在async函数中，错误通过try-catch捕获。在自动执行器中，当生成器内部出现错误（包括异步操作reject）时，我们使用generator.throw()将错误抛入生成器，这样生成器内部如果有try-catch，就能捕获错误。