Nuxt 提供了两个可组合的工具和一个内置库来在浏览器或服务器环境中执行数据获取：useFetch、useAsyncData 和 $fetch。

简而言之：

• $fetch 是进行网络请求的最简单方法。
• useFetch 是 $fetch 的包装器，在通用渲染中只获取一次数据。
• useAsyncData 类似于 useFetch，但提供了更细粒度的控制。

useFetch 和 useAsyncData 都共享一组通用的选项和模式，我们将在最后的部分详细介绍。

useFetch 和 useAsyncData 的必要性

Nuxt 是一个可以在服务器和客户端环境中运行同构（或通用）代码的框架。如果在 Vue 组件的 setup 函数中使用 $fetch 函数 来执行数据获取，这可能导致数据被获取两次，一次在服务器上（用于渲染 HTML），一次在客户端上（当 HTML 被激活时）。这可能导致激活问题、增加交互时间并导致不可预测的行为。

useFetch 和 useAsyncData 可组合工具通过确保如果在服务器上进行 API 调用，数据会在负载中转发到客户端，从而解决了这个问题。

负载是一个可以通过 useNuxtApp().payload 访问的 JavaScript 对象。它在客户端用于避免在激活期间代码在浏览器中执行时重新获取相同的数据。

<script setup lang="ts">
const { data } = await useFetch('/api/data')

async function handleFormSubmit() {
  const res = await $fetch('/api/submit', {
    method: 'POST',
    body: {
      // 我的表单数据
    }
  })
}
</script>

<template>
  <div v-if="data == null">
    No data
  </div>
  <div v-else>
    <form @submit="handleFormSubmit">
      <!-- 表单输入标签 -->
    </form>
  </div>
</template>

在上面的示例中，useFetch 将确保请求在服务器上发生，并正确转发到浏览器。$fetch 没有这样的机制，当请求仅从浏览器发出时，它是更好的选择。

Suspense

Nuxt 在底层使用 Vue 的 <Suspense> 组件，以防止在所有异步数据可用于视图之前进行导航。数据获取可组合工具可以帮助您利用此功能，并在每次调用时使用最适合的选项。

$fetch

Nuxt 包含 ofetch 库，并在整个应用程序中自动导入为 $fetch 别名。

async function addTodo() {
  const todo = await $fetch('/api/todos', {
    method: 'POST',
    body: {
      // 我的待办事项数据
    }
  })
}

将客户端头信息传递给 API

在服务器上调用 useFetch 时，Nuxt 将使用 useRequestFetch 来代理客户端头信息和 cookies（不包括不应转发的头信息，如 host）。

const { data } = await useFetch('/api/echo');

// /api/echo.ts
export default defineEventHandler(event => parseCookies(event))

或者，下面的示例展示了如何使用 useRequestHeaders 从服务器端请求（源自客户端）访问和发送 cookies 到 API。使用同构的 $fetch 调用，我们确保 API 端点可以访问用户浏览器最初发送的相同 cookie 头信息。这仅在您不使用 useFetch 时才需要。

const headers = useRequestHeaders(['cookie'])

async function getCurrentUser() {
  return await $fetch('/api/me', { headers })
}

useFetch

useFetch 可组合工具在底层使用 $fetch 在 setup 函数中进行 SSR 安全的网络调用。

<script setup lang="ts">
const { data: count } = await useFetch('/api/count')
</script>

<template>
  <p>页面访问次数: {{ count }}</p>
</template>

这个可组合工具是 useAsyncData 可组合工具和 $fetch 实用工具的包装器。

useAsyncData

useAsyncData 可组合工具负责包装异步逻辑，并在解析后返回结果。

在某些情况下，使用 useFetch 可组合工具并不合适，例如当 CMS 或第三方提供自己的查询层时。在这种情况下，您可以使用 useAsyncData 来包装您的调用，并仍然保留可组合工具提供的好处。

const { data, error } = await useAsyncData('users', () => myGetFunction('users'))

// 这也是可能的：
const { data, error } = await useAsyncData(() => myGetFunction('users'))

const { id } = useRoute().params

const { data, error } = await useAsyncData(`user:${id}`, () => {
  return myGetFunction('users', { id })
})

useAsyncData 可组合工具是包装和等待多个 $fetch 请求完成，然后处理结果的好方法。

const { data: discounts, status } = await useAsyncData('cart-discount', async () => {
  const [coupons, offers] = await Promise.all([
    $fetch('/cart/coupons'),
    $fetch('/cart/offers')
  ])

  return { coupons, offers }
})
// discounts.value.coupons
// discounts.value.offers

const offersStore = useOffersStore()

// 你不能这样做
await useAsyncData(() => offersStore.getOffer(route.params.slug))

返回值

useFetch 和 useAsyncData 具有相同的返回值，如下所示。

• data: 传入的异步函数的结果。
• refresh/execute: 可用于刷新 handler 函数返回的数据的函数。
• clear: 可用于将 data 设置为 undefined（或如果提供了 options.default() 的值），将 error 设置为 null，将 status 设置为 idle，并标记任何当前挂起的请求为已取消的函数。
• error: 如果数据获取失败，则为错误对象。
• status: 指示数据请求状态的字符串（"idle"、"pending"、"success"、"error"）。

默认情况下，Nuxt 会等待 refresh 完成后才能再次执行。

选项

useAsyncData 和 useFetch 返回相同的对象类型，并接受一组通用选项作为最后一个参数。它们可以帮助您控制可组合工具的行为，例如导航阻塞、缓存或执行。

Lazy

默认情况下，数据获取可组合工具将在使用 Vue 的 Suspense 导航到新页面之前等待其异步函数的解析。此功能可以在客户端导航时通过 lazy 选项忽略。在这种情况下，您将需要手动使用 status 值处理加载状态。

<script setup lang="ts">
const { status, data: posts } = useFetch('/api/posts', {
  lazy: true
})
</script>

<template>
  <!-- 您将需要处理加载状态 -->
  <div v-if="status === 'pending'">
    Loading ...
  </div>
  <div v-else>
    <div v-for="post in posts">
      <!-- 做一些事情 -->
    </div>
  </div>
</template>

您可以使用 useLazyFetch 和 useLazyAsyncData 作为执行相同操作的便捷方法。

const { status, data: posts } = useLazyFetch('/api/posts')

仅客户端获取

默认情况下，数据获取可组合工具将在客户端和服务器环境中执行其异步函数。将 server 选项设置为 false 以仅在客户端执行调用。在初始加载时，数据在激活完成之前不会被获取，因此您必须处理挂起状态，尽管在随后的客户端导航中，数据将在加载页面之前被等待。

结合 lazy 选项，这对于首次渲染时不需要的数据（例如，非 SEO 敏感数据）很有用。

/* 此调用在激活之前执行 */
const articles = await useFetch('/api/article')

/* 此调用将仅在客户端执行 */
const { status, data: comments } = useFetch('/api/comments', {
  lazy: true,
  server: false
})

useFetch 可组合工具旨在在 setup 方法中调用或直接在生命周期钩子的函数顶层调用，否则您应该使用 $fetch 方法。

最小化负载大小

pick 选项帮助您通过仅选择可组合工具返回的字段来最小化存储在 HTML 文档中的负载大小。

<script setup lang="ts">
/* 仅选择模板中使用的字段 */
const { data: mountain } = await useFetch('/api/mountains/everest', {
  pick: ['title', 'description']
})
</script>

<template>
  <h1>{{ mountain.title }}</h1>
  <p>{{ mountain.description }}</p>
</template>

如果您需要更多控制或映射多个对象，可以使用 transform 函数来更改查询结果。

const { data: mountains } = await useFetch('/api/mountains', {
  transform: (mountains) => {
    return mountains.map(mountain => ({ title: mountain.title, description: mountain.description }))
  }
})

缓存和重新获取

键

useFetch 和 useAsyncData 使用键来防止重新获取相同的数据。

• useFetch 使用提供的 URL 作为键。或者，可以在作为最后一个参数传递的 options 对象中提供 key 值。
• useAsyncData 如果第一个参数是字符串，则使用其作为键。如果第一个参数是执行查询的处理函数，则会为您生成一个唯一的文件名和 useAsyncData 实例的行号的键。

共享状态和选项一致性

当多个组件使用相同的键与 useAsyncData 或 useFetch 时，它们将共享相同的 data、error 和 status refs。这确保了组件之间的一致性，但需要某些选项保持一致。

以下选项在所有具有相同键的调用中必须一致：

• handler 函数
• deep 选项
• transform 函数
• pick 数组
• getCachedData 函数
• default 值

// ❌ 这将触发开发警告
const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })

以下选项在不触发警告的情况下可以安全地不同：

• server
• lazy
• immediate
• dedupe
• watch

// ✅ 这是允许的
const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: true })
const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: false })

如果您需要独立的实例，请使用不同的键：

// 这些是完全独立的实例
const { data: users1 } = useAsyncData('users-1', () => $fetch('/api/users'))
const { data: users2 } = useAsyncData('users-2', () => $fetch('/api/users'))

响应式键

您可以使用计算的 refs、普通的 refs 或 getter 函数作为键，允许动态数据获取在依赖项更改时自动更新：

// 使用计算属性作为键
const userId = ref('123')
const { data: user } = useAsyncData(
  computed(() => `user-${userId.value}`),
  () => fetchUser(userId.value)
)

// 当 userId 更改时，数据将自动重新获取
// 如果没有其他组件使用它，旧数据将被清除
userId.value = '456'

刷新和执行

如果您想手动获取或刷新数据，请使用可组合工具提供的 execute 或 refresh 函数。

<script setup lang="ts">
const { data, error, execute, refresh } = await useFetch('/api/users')
</script>

<template>
  <div>
    <p>{{ data }}</p>
    <button @click="() => refresh()">刷新数据</button>
  </div>
</template>

execute 函数是 refresh 的别名，工作方式完全相同，但对于非即时的情况更具语义性。

清除

如果您想清除提供的数据，无论出于何种原因，而不需要知道传递给 clearNuxtData 的特定键，可以使用可组合工具提供的 clear 函数。

const { data, clear } = await useFetch('/api/users')

const route = useRoute()
watch(() => route.path, (path) => {
  if (path === '/') clear()
})

监视

要在应用程序中的其他响应式值更改时重新运行您的获取函数，请使用 watch 选项。您可以将其用于一个或多个 可监视 元素。

const id = ref(1)

const { data, error, refresh } = await useFetch('/api/users', {
  /* 更改 id 将触发重新获取 */
  watch: [id]
})

请注意，监视响应式值不会更改获取的 URL。例如，这将继续获取用户的相同初始 ID，因为 URL 是在函数调用时构造的。

const id = ref(1)

const { data, error, refresh } = await useFetch(`/api/users/${id.value}`, {
  watch: [id]
})

如果您需要根据响应式值更改 URL，您可能需要使用计算 URL。

计算 URL

有时您可能需要从响应式值计算 URL，并在这些值更改时刷新数据。您可以将每个参数附加为响应式值，而不是绕道而行。Nuxt 将自动使用响应式值，并在每次更改时重新获取。

const id = ref(null)

const { data, status } = useLazyFetch('/api/user', {
  query: {
    user_id: id
  }
})

在更复杂的 URL 构建情况下，您可以使用回调作为返回 URL 字符串的计算 getter。

每当依赖项更改时，数据将使用新构建的 URL 获取。结合非即时，您可以在响应式元素更改之前等待获取。

<script setup lang="ts">
const id = ref(null)

const { data, status } = useLazyFetch(() => `/api/users/${id.value}`, {
  immediate: false
})

const pending = computed(() => status.value === 'pending');
</script>

<template>
  <div>
    {/* 在获取时禁用输入 */}
    <input v-model="id" type="number" :disabled="pending"/>

    <div v-if="status === 'idle'">
      输入用户 ID
    </div>

    <div v-else-if="pending">
      加载中 ...
    </div>

    <div v-else>
      {{ data }}
    </div>
  </div>
</template>

如果您需要在其他响应式值更改时强制刷新，您还可以监视其他值。

非即时

useFetch 可组合工具将在调用时立即开始获取数据。您可以通过设置 immediate: false 来防止这种情况，例如，等待用户交互。

这样，您将需要 status 来处理获取生命周期，并使用 execute 来启动数据获取。

<script setup lang="ts">
const { data, error, execute, status } = await useLazyFetch('/api/comments', {
  immediate: false
})
</script>

<template>
  <div v-if="status === 'idle'">
    <button @click="execute">获取数据</button>
  </div>

  <div v-else-if="status === 'pending'">
    加载评论中...
  </div>

  <div v-else>
    {{ data }}
  </div>
</template>

对于更精细的控制，status 变量可以是：

• idle 当获取尚未开始时
• pending 当获取已开始但尚未完成时
• error 当获取失败时
• success 当获取成功完成时

传递头信息和 Cookies

当我们在浏览器中调用 $fetch 时，用户头信息如 cookie 将直接发送到 API。

通常，在服务器端渲染期间，由于安全考虑，$fetch 不会包含用户浏览器的 cookies，也不会传递 fetch 响应中的 cookies。

然而，当在服务器上使用相对 URL 调用 useFetch 时，Nuxt 将使用 useRequestFetch 来代理头信息和 cookies（不包括不应转发的头信息，如 host）。

在 SSR 响应中从服务器端 API 调用传递 Cookies

如果您想在另一个方向上传递/代理 cookies，从内部请求返回到客户端，您需要自己处理。

import { appendResponseHeader } from 'h3'
import type { H3Event } from 'h3'

export const fetchWithCookie = async (event: H3Event, url: string) => {
  /* 从服务器端点获取响应 */
  const res = await $fetch.raw(url)
  /* 从响应中获取 cookies */
  const cookies = res.headers.getSetCookie()
  /* 将每个 cookie 附加到我们的传入请求 */
  for (const cookie of cookies) {
    appendResponseHeader(event, 'set-cookie', cookie)
  }
  /* 返回响应的数据 */
  return res._data
}

// 这个可组合工具将自动将 cookies 传递给客户端
const event = useRequestEvent()

const { data: result } = await useAsyncData(() => fetchWithCookie(event!, '/api/with-cookie'))

onMounted(() => console.log(document.cookie))

选项 API 支持

Nuxt 提供了一种在选项 API 中执行 asyncData 获取的方法。您必须将组件定义包装在 defineNuxtComponent 中才能使其工作。

export default defineNuxtComponent({
  /* 使用 fetchKey 选项提供唯一键 */
  fetchKey: 'hello',
  async asyncData () {
    return {
      hello: await $fetch('/api/hello')
    }
  }
})

从服务器到客户端的数据序列化

当使用 useAsyncData 和 useLazyAsyncData 将服务器上获取的数据传输到客户端时（以及任何其他利用 Nuxt 负载 的内容），负载使用 devalue 序列化。这使我们不仅可以传输基本的 JSON，还可以序列化和恢复/反序列化更高级的数据类型，如正则表达式、日期、Map 和 Set、ref、reactive、shallowRef、shallowReactive 和 NuxtError 等。

还可以为 Nuxt 不支持的类型定义自己的序列化/反序列化器。您可以在 useNuxtApp 文档中阅读更多信息。

从 API 路由序列化数据

从 server 目录获取数据时，响应使用 JSON.stringify 序列化。然而，由于序列化仅限于 JavaScript 原始类型，Nuxt 尽力将 $fetch 和 useFetch 的返回类型转换为匹配实际值。

示例

export default defineEventHandler(() => {
  return new Date()
})

// `data` 的类型被推断为字符串，即使我们返回了一个 Date 对象
const { data } = await useFetch('/api/foo')

自定义序列化函数

要自定义序列化行为，您可以在返回的对象上定义一个 toJSON 函数。如果您定义了一个 toJSON 方法，Nuxt 将尊重函数的返回类型，并且不会尝试转换类型。

export default defineEventHandler(() => {
  const data = {
    createdAt: new Date(),

    toJSON() {
      return {
        createdAt: {
          year: this.createdAt.getFullYear(),
          month: this.createdAt.getMonth(),
          day: this.createdAt.getDate(),
        },
      }
    },
  }
  return data
})

// `data` 的类型被推断为
// {
//   createdAt: {
//     year: number
//     month: number
//     day: number
//   }
// }
const { data } = await useFetch('/api/bar')

使用替代序列化器

Nuxt 目前不支持 JSON.stringify 的替代序列化器。然而，您可以将负载作为普通字符串返回，并利用 toJSON 方法来保持类型安全。

在下面的示例中，我们使用 superjson 作为我们的序列化器。

import superjson from 'superjson'

export default defineEventHandler(() => {
  const data = {
    createdAt: new Date(),

    // 解决类型转换问题
    toJSON() {
      return this
    }
  }

  // 使用 superjson 将输出序列化为字符串
  return superjson.stringify(data) as unknown as typeof data
})

import superjson from 'superjson'

// `date` 被推断为 { createdAt: Date }，您可以安全地使用 Date 对象方法
const { data } = await useFetch('/api/superjson', {
  transform: (value) => {
    return superjson.parse(value as unknown as string)
  },
})

配方

通过 POST 请求消费 SSE（服务器发送事件）

当通过 POST 请求消费 SSE 时，您需要手动处理连接。以下是如何做到这一点：

// 向 SSE 端点发起 POST 请求
const response = await $fetch<ReadableStream>('/chats/ask-ai', {
  method: 'POST',
  body: {
    query: "Hello AI, how are you?",
  },
  responseType: 'stream',
})

// 从响应中创建一个新的 ReadableStream，并使用 TextDecoderStream 获取文本数据
const reader = response.pipeThrough(new TextDecoderStream()).getReader()

// 在获取数据时读取数据块
while (true) {
  const { value, done } = await reader.read()

  if (done)
    break

  console.log('Received:', value)
}

并行请求

当请求彼此不依赖时，您可以使用 Promise.all() 并行执行它们以提高性能。

const { data } = await useAsyncData(() => {
  return Promise.all([
    $fetch("/api/comments/"), 
    $fetch("/api/author/12")
  ]);
});

const comments = computed(() => data.value?.[0]);
const author = computed(() => data.value?.[1]);