useAxiosFetch 使用文档

useAxiosFetch 是一个基于 Axios 的 HTTP 请求工具，专为 Nuxt 3 应用设计，支持服务端渲染和客户端请求。它提供了请求缓存、统一错误处理等高级功能。

特性

• ✅ 完全类型化的 API
• ✅ 服务端渲染支持 (SSR)
• ✅ 请求缓存机制（基于 Nuxt useAsyncData）
• ✅ 统一错误处理（自动显示错误通知）
• ✅ 防抖错误通知（3秒内相同消息不重复提示）
• ✅ 自动身份验证处理（401 自动跳转登录）

安装

该组件已经集成在项目中，无需额外安装。

基本用法

导入

import {useAxiosFetch} from "~/composables/useAxiosFetch"

GET 请求

const {data, error} = await useAxiosFetch("/api/users", {
  method: "GET",
  params: {page: 1},
})

POST 请求

const {data, error} = await useAxiosFetch("/api/users", {
  method: "POST",
  data: {
    name: "John",
    email: "john@example.com",
  },
})

PUT 请求

const {data, error} = await useAxiosFetch("/api/users/1", {
  method: "PUT",
  data: {
    name: "Updated Name",
  },
})

DELETE 请求

const {data, error} = await useAxiosFetch("/api/users/1", {
  method: "DELETE",
})

配置选项

interface RequestOptions {
  // Axios配置
  data?: any              // 请求体数据
  params?: Record<string, any>  // URL参数
  method?: string         // HTTP方法
  headers?: Record<string, string>  // 请求头
  baseURL?: string       // 基础URL
  timeout?: number       // 超时时间（毫秒）

  // Nuxt useAsyncData配置
  server?: boolean      // 是否在服务端执行（默认true）
  lazy?: boolean       // 是否延迟执行（默认false）
  immediate?: boolean  // 是否立即执行（默认true）
  deep?: boolean      // 是否深度监听（默认false）
  watch?: any[] | false  // 监听依赖
  transform?: (input: any) => any  // 转换函数
  pick?: string[]     // 选择字段
  default?: () => any // 默认值函数
}

响应类型

interface RequestResponse<T> {
  data: T | null  // 响应数据
  error: any      // 错误对象
}

错误处理

useAxiosFetch 会自动处理错误并在前端显示错误通知：

• 401 未授权：自动跳转到登录页
• 404 未找到：显示"Resource Not Found"错误
• 其他错误：显示"Server Error"错误

错误通知有3秒防抖机制，相同错误消息在短时间内只会显示一次。

请求缓存

useAxiosFetch 使用 Nuxt 的 useAsyncData 实现请求缓存。缓存键由以下因素组成：

• URL
• HTTP 方法
• 请求参数
• 请求体数据

这确保了相同的请求会从缓存中读取，提高性能。

最佳实践

1. 使用类型参数

interface User {
  id: number
  name: string
  email: string
}

const {data} = await useAxiosFetch<User>("/api/users/1")
// data 的类型为 User | null

2. 在组件中使用

<template>
  <div v-if="!data">加载中...</div>
  <div v-else-if="error">出错了: {{ error.message }}</div>
  <div v-else>{{ data }}</div>
</template>

<script setup>
const {data, error} = await useAxiosFetch("/api/users")
</script>

3. 组合多个请求

const [users, posts] = await Promise.all([
  useAxiosFetch("/api/users", {method: "GET"}),
  useAxiosFetch("/api/posts", {method: "GET"})
])

// 访问数据
const userData = users.data
const postsData = posts.data

4. 动态请求

<script setup>
import {ref} from "vue"
import {useAxiosFetch} from "~/composables/useAxiosFetch"

const users = ref(null)

async function fetchUsers(page: number = 1) {
  const {data} = await useAxiosFetch(`/api/users?page=${page}`, {
    method: "GET",
  })
  users.value = data
}

// 初始加载
fetchUsers()
</script>

注意事项

1. 服务端渲染（SSR）支持：默认情况下，请求会在服务端执行
2. 401 错误会自动跳转到登录页
3. 错误通知有3秒防抖机制
4. 缓存基于 URL、方法、参数和数据的组合
5. 建议使用类型参数以获得更好的类型提示

技术细节

统一响应格式

API 响应应遵循以下格式：

{
  "code": 0,
  "message": "success",
  "data": {}
}

• code: 0 表示成功
• code !== 0 表示业务错误

全局配置

以下配置在 useAxiosFetch 中全局设置：

{
  baseURL: process.env.HOST,  // 从环境变量读取
  timeout: 10000,  // 10秒超时
  headers: {
    'Content-Type': 'application/json',
  },
}