useApiFetch

基于 Nuxt useFetch 封装的 API 请求 composable，提供自动认证、业务状态码检查和 Toast 提示。

Usage

使用自动导入的 useApiFetch composable 进行 API 请求，基于 Nuxt useFetch 封装，提供自动认证、数据解包、业务状态码检查和统一的错误处理。

<script setup lang="ts">
interface User {
  id: number
  name: string
  email: string
}

// 基础用法(自动解包 data 字段)
const { data, pending, error, refresh } = await useApiFetch<User[]>('/users')

// POST 请求
const { data } = await useApiFetch('/users', {
  method: 'POST',
  body: { name: 'test', email: 'test@example.com' }
})

// 使用其他端点
const { data } = await useApiFetch('/users', { endpoint: 'v2' })
</script>

useApiFetch 继承 Nuxt useFetch 的所有功能，同时提供额外的 API 集成特性。
自动从 session 获取 token 并添加到请求头(通过 $api 实例)。
自动检查业务状态码并抛出错误。
内置 Toast 提示，支持自定义配置。

useApiFetch 在服务端和客户端均可执行。如需仅在客户端执行请求，请使用 useClientApiFetch。完整的 useFetch 选项参考: Nuxt useFetch 文档

了解 API 系统的全局配置选项，包括端点、认证、Toast 等

数据解包

useApiFetch 会自动解包 API 响应的 data 字段:

// API 响应格式
{
  code: 200,
  message: 'Success',
  data: { id: 1, name: 'test' }  // 这部分会被自动解包
}

// 使用时直接声明 data 字段的类型
const { data } = await useApiFetch<User>('/user')
// data.value = { id: 1, name: 'test' }

如果响应格式不同，可以使用 skipBusinessCheck 跳过解包，或使用 transform 自定义转换逻辑。

业务状态码检查

默认情况下，useApiFetch 会检查业务状态码(通过模块配置的 response 选项):

// 默认配置
{
  response: {
    codeKey: 'code',
    successCodes: [200, 0]
  }
}

当业务状态码不匹配时，会自动抛出错误并显示 Toast:

// 业务状态码错误
{
  code: 400,
  message: '用户名已存在'
}
// 自动抛出错误，显示 Toast: "用户名已存在"

可以通过 skipBusinessCheck: true 禁用此功能:

const { data } = await useApiFetch('/users', {
  skipBusinessCheck: true
})

Toast 提示

内置 Toast 提示，支持请求级配置:

// 禁用所有 Toast
const { data } = await useApiFetch('/users', {
  toast: false
})

// 仅显示错误提示
const { data } = await useApiFetch('/users', {
  toast: { success: false }
})

// 使用快捷文本
const { data } = await useApiFetch('/users', {
  toast: {
    successMessage: '创建成功!',
    errorMessage: '创建失败,请重试'
  }
})

// 使用完整的 Toast 属性
const { data } = await useApiFetch('/users', {
  toast: {
    success: {
      title: '创建成功',
      description: '用户已添加到系统',
      color: 'primary',
      icon: 'i-lucide-circle-check'
    },
    error: {
      title: '创建失败',
      description: '请检查输入信息',
      color: 'danger',
      timeout: 5000
    }
  }
})

自定义 Hooks

支持自定义请求钩子，与内置钩子合并执行:

const { data } = await useApiFetch('/users', {
  onRequest({ request, options }) {
    console.log('发送请求:', request)
  },
  onRequestError({ request, error }) {
    console.error('请求错误:', error)
  },
  onResponse({ response }) {
    console.log('收到响应:', response._data)
  },
  onResponseError({ response }) {
    console.error('响应错误:', response.status)
  }
})

用户钩子会在内置钩子之后执行，不会覆盖内置的认证和 Toast 逻辑。

API

useApiFetch()

useApiFetch<ResT = unknown, DataT = ResT>(url: string | (() => string), options?: UseApiFetchOptions<ResT, DataT>): UseApiFetchReturn<DataT>

创建 API 请求。

Parameters

url

string | (() => string) required

请求 URL 或返回 URL 的函数。支持响应式 URL。

options

UseApiFetchOptions<ResT, DataT>

请求配置选项。支持所有 Nuxt useFetch 选项，以及额外的 API 集成选项。

API 集成选项

endpoint

string

使用指定的端点配置。默认使用 $api 的默认端点。

toast

RequestToastOptions | false

Toast 提示配置。设为 false 禁用 Toast。

skipBusinessCheck

boolean

跳过业务状态码检查。默认 false。

请求选项 (继承自 useFetch)

method

HTTP 请求方法。默认 'GET'。

query

Record<string, any>

URL 查询参数，会自动序列化到 URL。

params

Record<string, any>

query 的别名。

body

RequestInit['body'] | Record<string, any>

请求体。对于 POST/PUT/PATCH 请求，会自动序列化为 JSON。

headers

Record<string, string> | [key: string, value: string][] | Headers

请求头。

baseURL

string

基础 URL。通常通过 endpoint 选项配置，无需手动设置。

响应处理

transform

(input: ResT) => DataT | Promise<DataT>

转换响应数据的函数。接收解包后的 data 字段，返回最终数据。

pick

string[]

仅选择响应数据的指定字段。

default

() => DataT

设置默认值的工厂函数。

执行选项

immediate

boolean

是否立即执行请求。设为 false 时需手动调用 execute()。默认 true。

lazy

boolean

是否使用 lazy 模式。lazy 模式下不会阻塞导航，初始 pending 为 false。默认 false。

server

boolean

是否在服务端执行请求。默认 true。

watch

MultiWatchSources

监听的响应式源，变化时自动重新请求。可以是 ref、reactive 对象或数组。

deep

boolean

是否深度监听 watch 的对象。默认 true。

缓存与去重

key

string

自定义缓存键。用于多个请求之间共享数据或去重。

dedupe

'cancel' | 'defer'

重复请求的处理策略。默认 cancel

'cancel' - 取消待处理的请求
'defer' - 不发起新请求

getCachedData

(key: string) => DataT

从缓存中获取数据的函数。返回值将用作初始 data。

请求钩子

onRequest

(context: FetchContext) => Promise<void> | void

请求发送前的钩子。与内置钩子合并执行。

onRequestError

(context: FetchContext & { error: Error }) => Promise<void> | void

请求错误时的钩子。与内置钩子合并执行。

onResponse

(context: FetchContext & { response: Response }) => Promise<void> | void

收到响应时的钩子。与内置钩子合并执行。

onResponseError

(context: FetchContext & { response: Response }) => Promise<void> | void

响应错误时的钩子(4xx/5xx)。与内置钩子合并执行。

Type Parameters

ResT

type

API 响应中 data 字段的原始类型。

DataT

type

transform 转换后的最终类型。默认等于 ResT。

Returns

返回 useFetch 的响应对象，包含以下属性:

data

Ref<DataT | null>

响应数据(已解包和转换)。初始值为 null，请求成功后更新为实际数据。

error

Ref<FetchError | null>

错误对象。包含网络错误、业务状态码错误等。

status

Ref<'idle' | 'pending' | 'success' | 'error'>

请求状态。

'idle' - 尚未开始(仅 immediate: false 时)
'pending' - 请求进行中
'success' - 请求成功
'error' - 请求失败

pending

Ref<boolean>

是否正在请求中。等价于 status.value === 'pending'。

refresh

(opts?: { dedupe?: boolean }) => Promise<void>

刷新数据，重新执行请求。别名: execute。

execute

(opts?: { dedupe?: boolean }) => Promise<void>

refresh 的别名。手动执行请求(常用于 immediate: false 时)。

clear

() => void

清空状态。将 data 设为 null、error 设为 null、status 设为 'idle'。

Changelog

6ebb7 — refactor: 更新运行时实现以适配新配置架构

f2709 — refactor: 重构 API 配置架构并新增上传下载组件

277ea — refactor: 重构 API 请求模块架构

6e8f3 — chore: 🔧 更新文档、示例与自动生成的类型

b31fb — fix: 修复 useClientApiFetch 立即执行问题

3bffb — feat: 重构 useApiFetch 基于 useFetch 和自定义 $fetch 实例

87762 — refactor: 重构 useApiFetch 基于 useAsyncData + $api

419b5 — feat: 添加自定义 API Fetch 框架

useAutoForm

用于创建类型化 Zod Schema 和管理 AutoForm 控件的 composable。

useClientApiFetch

仅客户端执行的 API 请求 composable，适用于非 SEO 敏感数据。