vue api调用 - 完整解决方案与实战教程

在 Vue 3 组合式 API 与 Vite 构建的现代前端项目中，调用后端 RESTful 接口早已不是简单写个 fetch 就能了事。尤其是在中大型后台管理系统里，你往往需要处理 跨域代理、请求拦截、Token 自动刷新、并发请求竞态、组件卸载后异步响应导致的状态污染，以及 loading 状态与错误边界的统一管理。很多开发者把 Vue 的响应式系统和 Axios 混用后，发现接口调用看似成功，但页面数据就是不更新，或者切换路由后控制台疯狂报 “Cannot read properties of null”。本文将从真实业务场景出发，逐层拆解这些高频坑点，并给出一套可直接落地的封装方案。

问题现象：Vue API 调用中的典型翻车现场

• 数据不更新：在 onMounted 中调用接口，赋值给 ref 后模板无变化，控制台却能看到新数据。
• 竞态覆盖：快速切换 Tab 或搜索关键词，先发出的慢请求覆盖了后发出的快请求结果。
• 内存泄漏与报错：组件已卸载，接口才返回，此时修改 reactive 对象触发 Vue 警告甚至报错。
• Token 失效处理混乱：401 时多个请求同时触发刷新 Token，导致刷新接口被重复调用，甚至死循环。
• 跨域与代理失效：开发环境 vite.config.js 配置了 proxy，但生产环境路径拼接错误，接口 404。

原因分析：为什么 Vue 中 API 调用容易出问题？

核心原因在于 Vue 的响应式系统与异步请求的生命周期并不同步。具体来说：

1. 响应式丢失：直接解构 reactive 对象或替换整个 ref 的 .value 时，若未保持引用，Vue 无法追踪变化。更隐蔽的是，在 axios 的 then 中直接赋值 this.list = res.data（选项式 API）通常没问题，但在组合式 API 中若使用 const { list } = reactive({ list: [] })，解构后的 list 已失去响应性。
2. 竞态条件：浏览器对同一域名的并发请求数有限制，但请求返回顺序完全不可控。Vue 不会自动取消旧请求，导致旧数据覆盖新数据。
3. 组件卸载后的副作用：onUnmounted 中若未取消未完成的请求，回调仍会执行，此时组件实例已销毁，修改状态会触发警告。
4. 拦截器设计缺陷：多数项目只在请求拦截器加 Token，却未在响应拦截器统一处理 401 刷新逻辑，导致每个请求各自为战。
5. 环境变量与代理混淆：Vite 的 import.meta.env 与 process.env 混用，或 baseURL 在开发/生产环境未正确区分。

解决方案（附完整代码）

下面给出一套基于 Vue 3 + Axios + TypeScript 的完整封装，涵盖请求取消、Token 刷新队列、响应式安全赋值和统一错误处理。

1. 封装 Axios 实例与拦截器

// src/utils/request.ts
import axios, { AxiosError, InternalAxiosRequestConfig, AxiosResponse } from 'axios';

// 是否正在刷新 Token
let isRefreshing = false;
// 等待队列：存储刷新 Token 期间挂起的请求
let pendingQueue: Array<(token: string) => void> = [];

const service = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL, // 从 .env 读取
  timeout: 10000,
});

// 请求拦截器：注入 Token
service.interceptors.request.use(
  (config: InternalAxiosRequestConfig) => {
    const token = localStorage.getItem('access_token');
    if (token && config.headers) {
      config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
  },
  (error) => Promise.reject(error)
);

// 响应拦截器：统一处理 401 与业务错误
service.interceptors.response.use(
  (response: AxiosResponse) => {
    const { code, data, message } = response.data;
    if (code === 200) return data;
    // 业务错误统一提示
    console.error('业务错误:', message);
    return Promise.reject(new Error(message));
  },
  async (error: AxiosError) => {
    const { response, config } = error;
    if (response?.status === 401 && config) {
      // 如果正在刷新，将当前请求加入队列等待
      if (isRefreshing) {
        return new Promise((resolve) => {
          pendingQueue.push((newToken: string) => {
            config.headers!.Authorization = `Bearer ${newToken}`;
            resolve(service(config));
          });
        });
      }
      isRefreshing = true;
      try {
        const newToken = await refreshToken(); // 调用刷新接口
        localStorage.setItem('access_token', newToken);
        // 执行队列中的请求
        pendingQueue.forEach((cb) => cb(newToken));
        pendingQueue = [];
        config.headers!.Authorization = `Bearer ${newToken}`;
        return service(config);
      } catch (refreshError) {
        // 刷新失败，跳转登录
        window.location.href = '/login';
        return Promise.reject(refreshError);
      } finally {
        isRefreshing = false;
      }
    }
    return Promise.reject(error);
  }
);

// 模拟刷新 Token 接口
async function refreshToken(): Promise<string> {
  const res = await axios.post('/api/refresh', {
    refresh_token: localStorage.getItem('refresh_token'),
  });
  return res.data.access_token;
}

export default service;

2. 在组件中安全调用并处理竞态与卸载

// src/composables/useUserList.ts
import { ref, onUnmounted } from 'vue';
import request from '@/utils/request';

export function useUserList() {
  const list = ref<User[]>([]);
  const loading = ref(false);
  const error = ref<string | null>(null);
  // 用于取消请求的 AbortController
  let controller: AbortController | null = null;

  const fetchList = async (keyword: string) => {
    // 取消上一次未完成的请求，避免竞态
    if (controller) controller.abort();
    controller = new AbortController();

    loading.value = true;
    error.value = null;
    try {
      // 注意：直接给 ref.value 赋值，保持响应性
      list.value = await request.get('/api/users', {
        params: { keyword },
        signal: controller.signal, // 传入取消信号
      });
    } catch (err: any) {
      if (err.name === 'CanceledError') return; // 主动取消不报错
      error.value = err.message;
    } finally {
      loading.value = false;
    }
  };

  // 组件卸载时取消请求，防止内存泄漏
  onUnmounted(() => {
    if (controller) controller.abort();
  });

  return { list, loading, error, fetchList };
}

3. 排查与配置检查清单

• 检查 vite.config.js 中 server.proxy 是否将 /api 正确转发到后端地址，且 changeOrigin: true。
• 确认 .env.development 与 .env.production 中 VITE_API_BASE_URL 分别指向代理前缀和真实域名。
• 在浏览器 Network 面板中查看请求是否携带 Authorization 头，以及响应状态码是否为 200。
• 若使用 reactive 定义列表，务必直接操作 state.list，不要解构。
• 对于频繁触发的搜索，使用 lodash.debounce 或 watch + setTimeout 降低请求频率。

以上方案已在多个日活十万级后台项目中验证，能有效解决 90% 以上的 Vue API 调用疑难杂症。记住：响应式赋值要保引用，异步请求要能取消，Token 刷新要排队，组件卸载要清理。把这四点做成肌肉记忆，你的接口层将稳如磐石。