useApiFetch

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

用法

使用自动导入的 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 提示，支持自定义配置。

数据请求模式

Movk Nuxt 提供三种数据请求 composable，签名一致，按执行时机选择：

Composable	执行时机	阻塞导航	场景
`useApiFetch`	SSR + CSR	是	首屏核心数据
`useLazyApiFetch`	SSR + CSR	否	次要 / 非首屏数据
`useClientApiFetch`	仅 CSR	否	非 SEO 敏感数据

useApiFetch 在 SSR 阶段就发起请求，首屏直出数据：

ready

{
  "id": "me",
  "name": "Movk Demo",
  "email": "demo@movk.dev",
  "avatar": "/avatar.png",
  "role": "developer",
  "issuedAt": "2026-06-21T11:00:41.697Z"
}

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

const { data, pending, error, refresh } = await useApiFetch<Profile>('/profile')
</script>

<template>
  <div class="flex flex-col gap-3">
    <div class="flex items-center gap-2 flex-wrap">
      <UBadge v-if="pending" color="warning" variant="subtle">
        pending
      </UBadge>
      <UBadge v-else-if="error" color="error" variant="subtle">
        error
      </UBadge>
      <UBadge v-else color="success" variant="subtle">
        ready
      </UBadge>
      <UButton size="sm" variant="outline" icon="i-lucide-refresh-cw" @click="refresh()">
        刷新
      </UButton>
    </div>
    <pre class="text-xs p-3 rounded bg-elevated overflow-auto">{{ error ? { error: error.message } : data }}</pre>
  </div>
</template>

数据解包与转换

useApiFetch 接收到的已是 $api 解包后的业务数据，泛型 T 直接声明该数据类型；transform 接收解包后的数据做二次转换：

// 泛型 T 直接声明业务数据类型（即 data 字段的类型）
const { data } = await useApiFetch<User>('/user')
// data.value = { id: 1, name: 'test' }

// 结合 transform 做二次转换
const { data } = await useApiFetch<{ content: User[] }, SelectItem[]>('/users', {
  transform: ({ content }) => content.map(u => ({ label: u.name, value: u.id }))
})

解包机制、skipUnwrap / skipBusinessCheck 的交互示例见 $api 页

业务状态码检查

$api 拦截器自动检查业务状态码，不在 successCodes 中时抛出 ApiError（见下方错误分类）。传 skipBusinessCheck: true 跳过校验（不抛 ApiError），但仍解包 dataKey 字段：

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

业务校验与 skipBusinessCheck 的交互示例见 $api 页

错误分类

模块只产出 ApiError（业务错误）一种自定义错误，其余均为 ofetch 原生 FetchError；通过 isBusinessError 与 statusCode 区分场景。下拉切换错误类型观察 error.value 形态：

business：HTTP 200 但 code 不在 successCodes 内 → ApiError，isBusinessError 为 true。
http-400 / http-500：原生 FetchError，statusCode 为对应码。
http-422：FetchError 的 data 字段携带服务端补充信息。
network：连接被强制断开 → 无 statusCode 的 FetchError。

类型

模块只产出 ApiError（业务错误）一种自定义错误，其余均为 ofetch 原生 FetchError；通过 isBusinessError 与 statusCode 区分场景。

<script setup lang="ts">
import type { ApiError } from '@movk/nuxt'
import type { FetchError } from 'ofetch'

const props = defineProps<{
  mode: 'business' | 'http-400' | 'http-422' | 'http-500' | 'network'
}>()

const urlMap: Record<typeof props.mode, string> = {
  'business': '/demo/errors?type=business',
  'http-400': '/profile?fail=1',
  'http-422': '/demo/errors?type=422',
  'http-500': '/demo/errors?type=500',
  'network': '/demo/errors?type=network'
}

const { error, execute } = useApiFetch(() => urlMap[props.mode], {
  immediate: false,
  toast: false
})

const info = computed(() => {
  const err = error.value
  if (!err) return null
  const apiErr = err as Partial<ApiError>
  const fetchErr = err as FetchError
  return {
    kind: apiErr.isBusinessError ? 'ApiError（业务错误）' : 'FetchError',
    statusCode: apiErr.statusCode ?? fetchErr.statusCode ?? null,
    message: err.message,
    isBusinessError: apiErr.isBusinessError ?? false,
    data: fetchErr.data ?? null
  }
})
</script>

<template>
  <div class="flex flex-col gap-3">
    <UButton size="sm" color="error" variant="outline" icon="i-lucide-circle-alert" @click="execute()">
      触发 {{ mode }}
    </UButton>
    <p class="text-xs text-muted">
      模块只产出 <code>ApiError</code>（业务错误）一种自定义错误，其余均为 ofetch 原生 <code>FetchError</code>；通过 <code>isBusinessError</code> 与 <code>statusCode</code> 区分场景。
    </p>
    <pre class="text-xs p-3 rounded bg-elevated overflow-auto">{{ info }}</pre>
  </div>
</template>

Toast 提示

toast 选项支持请求级配置：false 全关、{ success: false } 仅留错误、successMessage / errorMessage 快捷文本，或传完整 Toast 属性（color、icon、duration 等）：

// 关闭 Toast / 仅保留错误提示 / 快捷文本
await useApiFetch('/users', { toast: false })
await useApiFetch('/users', { toast: { success: false } })
await useApiFetch('/users', {
  toast: { successMessage: '创建成功!', errorMessage: '创建失败,请重试' }
})

// 完整 Toast 属性
await useApiFetch('/users', {
  toast: {
    success: { title: '创建成功', color: 'success', icon: 'i-lucide-circle-check' },
    error: { title: '创建失败', color: 'error', duration: 5000 }
  }
})

五种 Toast 模式的交互示例见 $api 页

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

options

UseApiFetchOptions<T, DataT>

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

API 集成选项

endpoint

string

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

toast

RequestToastOptions | false

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

skipBusinessCheck

boolean

跳过业务状态码检查（不抛出 ApiError），但仍会解包 dataKey 字段。默认 false。

skipUnwrap

boolean

跳过数据解包。设为 true 时返回 code/message/data 完整信封。与 skipBusinessCheck 正交。默认 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: T) => DataT | Promise<DataT>

转换响应数据的函数。接收已解包的业务数据，返回最终数据。

pick

string[]

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

default

() => DataT

设置默认值的工厂函数。

执行选项

immediate

boolean

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

lazy

boolean

是否使用 lazy 模式。lazy 模式下不会阻塞客户端导航，数据在后台加载。默认 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

type

业务数据类型（已由 $api 自动解包）。即 API 响应中 data 字段的数据类型。

DataT

type

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

Returns

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

data

Ref<DataT | null>

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

error

Ref<FetchError | ApiError | null>

错误对象。网络错误为 FetchError，业务状态码错误为 ApiError（包含 statusCode、response、isBusinessError 属性）。

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

No recent changes

hooks

通过 Nuxt 运行时 Hook 扩展 API 系统行为，实现全局请求拦截、错误处理和 401 自定义处理。

useLazyApiFetch

懒加载版 useApiFetch，不阻塞客户端导航，页面立即显示。