数据获取

Nuxt 提供了可组合函数来处理应用程序中的数据获取。

Nuxt 提供了两个可组合函数和一个内置库,用于在浏览器或服务器环境中执行数据获取:useFetchuseAsyncData$fetch

简而言之

  • $fetch 是发出网络请求最简单的方法。
  • useFetch$fetch 的一个封装,它在通用渲染中只获取一次数据。
  • useAsyncData 类似于 useFetch,但提供了更精细的控制。

无论是 useFetch 还是 useAsyncData 都有一套共同的选项和模式,我们将在最后几节中详细介绍。

useFetchuseAsyncData 的需求

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

useFetchuseAsyncData 可组合函数通过确保如果 API 调用发生在服务器上,数据会以有效负载的形式转发到客户端来解决此问题。

有效负载是一个 JavaScript 对象,可以通过 useNuxtApp().payload 访问。它在客户端使用,以避免在代码在浏览器水合期间执行时重复获取相同的数据。

使用Nuxt DevToolsPayload tab 中检查这些数据。
app/app.vue
<script setup lang="ts">
const { data } = await useFetch('/api/data')

async function handleFormSubmit () {
  const res = await $fetch('/api/submit', {
    method: 'POST',
    body: {
      // My form data
    },
  })
}
</script>

<template>
  <div v-if="data == undefined">
    No data
  </div>
  <div v-else>
    <form @submit="handleFormSubmit">
      <!-- form input tags -->
    </form>
  </div>
</template>

在上面的示例中,useFetch 将确保请求发生在服务器中,并正确转发到浏览器。$fetch 没有这种机制,当请求完全由浏览器发出时,它是一个更好的选择。

Suspense

Nuxt 在底层使用 Vue 的<Suspense>组件,以防止在所有异步数据都可用之前进行导航。数据获取可组合函数可以帮助您利用此功能,并根据每次调用使用最适合的方法。

您可以添加 <NuxtLoadingIndicator> 以在页面导航之间添加进度条。

$fetch

Nuxt 包含了ofetch库,并自动导入为您的应用程序中全局的 $fetch 别名。

pages/todos.vue
<script setup lang="ts">
async function addTodo () {
  const todo = await $fetch('/api/todos', {
    method: 'POST',
    body: {
      // My todo data
    },
  })
}
</script>
请注意,仅使用 $fetch 不会提供网络调用去重和导航阻止
建议将 $fetch 用于客户端交互(基于事件)或与 useAsyncData 结合使用,用于获取初始组件数据。
阅读更多关于 $fetch 的信息。

将客户端头传送到 API

在服务器上调用 useFetch 时,Nuxt 将使用 useRequestFetch 来代理客户端头和 cookie(不应转发的头除外,例如 host)。

<script setup lang="ts">
const { data } = await useFetch('/api/echo')
</script>
// /api/echo.ts
export default defineEventHandler(event => parseCookies(event))

另外,下面的示例展示了如何使用 useRequestHeaders 从服务器端请求(源自客户端)访问 cookie 并将其发送到 API。通过使用同构的 $fetch 调用,我们确保 API 端点可以访问用户浏览器最初发送的相同 cookie 头。这仅在您不使用 useFetch 时才需要。

<script setup lang="ts">
const headers = useRequestHeaders(['cookie'])

async function getCurrentUser () {
  return await $fetch('/api/me', { headers })
}
</script>
您还可以使用 useRequestFetch 自动将标头代理到调用。
在将标头代理到外部 API 之前,请务必谨慎,并且只包含您需要的标头。并非所有标头都可以安全地绕过,并且可能会引入意外行为。以下是通常不应代理的常见标头列表
  • host, accept
  • content-length, content-md5, content-type
  • x-forwarded-host, x-forwarded-port, x-forwarded-proto
  • cf-connecting-ip, cf-ray

useFetch

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

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

<template>
  <p>Page visits: {{ count }}</p>
</template>

这个可组合函数是 useAsyncData 可组合函数和 $fetch 工具的封装。

阅读更多信息:Docs > 4 X > API > Composables > Use Fetch
Docs > 4 X > Examples > Features > Data Fetching 中阅读和编辑实时示例。

useAsyncData

useAsyncData 可组合函数负责封装异步逻辑并在解析后返回结果。

useFetch(url) 几乎等同于 useAsyncData(url, () => event.$fetch(url))
它是最常见用例的开发者体验糖。(您可以从useRequestFetch 中找到更多关于 event.fetch 的信息。)

在某些情况下,使用 useFetch 可组合函数是不合适的,例如当 CMS 或第三方提供自己的查询层时。在这种情况下,您可以使用 useAsyncData 封装您的调用,并仍然保留可组合函数提供的优点。

app/pages/users.vue
<script setup lang="ts">
const { data, error } = await useAsyncData('users', () => myGetFunction('users'))

// This is also possible:
const { data, error } = await useAsyncData(() => myGetFunction('users'))
</script>
useAsyncData 的第一个参数是一个唯一的键,用于缓存第二个参数(查询函数)的响应。如果直接传递查询函数,可以忽略此键,键将自动生成。

由于自动生成的键仅考虑调用 useAsyncData 的文件和行,因此建议始终创建自己的键,以避免意外行为,例如当您创建自己的自定义可组合函数封装 useAsyncData 时。

设置键对于使用 useNuxtData 在组件之间共享相同数据或刷新特定数据非常有用。
app/pages/users/[id].vue
<script setup lang="ts">
const { id } = useRoute().params

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

useAsyncData 可组合函数是封装并等待多个 $fetch 请求完成,然后处理结果的好方法。

<script setup lang="ts">
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
</script>
useAsyncData 用于获取和缓存数据,而不是触发副作用,例如调用 Pinia actions,因为这可能会导致意外行为,例如重复执行空值。如果您需要触发副作用,请使用 callOnce 工具来执行此操作。
<script setup lang="ts">
const offersStore = useOffersStore()

// you can't do this
await useAsyncData(() => offersStore.getOffer(route.params.slug))
</script>
阅读更多关于 useAsyncData 的信息。

返回值

useFetchuseAsyncData 具有下面列出的相同返回值。

  • data:作为参数传入的异步函数的结果。
  • refresh/execute:一个可用于刷新 handler 函数返回的数据的函数。
  • clear:一个可用于将 data 设置为 undefined(如果提供了 options.default(),则为该值),将 error 设置为 undefined,将 status 设置为 idle,并标记任何当前待处理的请求为已取消的函数。
  • error:如果数据获取失败,则为错误对象。
  • status:一个字符串,指示数据请求的状态("idle""pending""success""error")。
dataerrorstatus 是 Vue ref,可在 <script setup> 中通过 .value 访问。

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

如果你没有在服务器上获取数据(例如,使用 server: false),那么在水合完成之前数据将不会被获取。这意味着即使你在客户端等待 useFetchdata<script setup> 中仍将为 null。

选项

useAsyncDatauseFetch 返回相同的对象类型,并接受一组共同的选项作为它们的最后一个参数。它们可以帮助您控制可组合函数的行为,例如导航阻塞、缓存或执行。

惰性

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

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

<template>
  <!-- you will need to handle a loading state -->
  <div v-if="status === 'pending'">
    Loading ...
  </div>
  <div v-else>
    <div v-for="post in posts">
      <!-- do something -->
    </div>
  </div>
</template>

您还可以使用 useLazyFetchuseLazyAsyncData 作为便捷方法来执行相同的操作。

<script setup lang="ts">
const { status, data: posts } = useLazyFetch('/api/posts')
</script>
阅读更多关于 useLazyFetch 的信息。
阅读更多关于 useLazyAsyncData 的信息。

仅客户端获取

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

lazy 选项结合使用,这对于在首次渲染时不需要的数据(例如,非 SEO 敏感数据)非常有用。

/* This call is performed before hydration */
const articles = await useFetch('/api/article')

/* This call will only be performed on the client */
const { status, data: comments } = useFetch('/api/comments', {
  lazy: true,
  server: false,
})

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

最小化有效负载大小

pick 选项通过仅选择您希望从可组合函数返回的字段来帮助您最小化存储在 HTML 文档中的有效负载大小。

<script setup lang="ts">
/* only pick the fields used in your template */
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 }))
  },
})
picktransform 都不能阻止不需要的数据最初被获取。但是它们会阻止不需要的数据被添加到从服务器传输到客户端的有效负载中。

缓存和重新获取

useFetchuseAsyncData 使用键来防止重复获取相同的数据。

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

共享状态和选项一致性

当多个组件使用相同的键与 useAsyncDatauseFetch 时,它们将共享相同的 dataerrorstatus 引用。这确保了组件之间的一致性,但要求某些选项保持一致。

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

  • handler 函数
  • deep 选项
  • transform 函数
  • pick 数组
  • getCachedData 函数
  • default
// ❌ This will trigger a development warning
const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })

以下选项可以安全地不同,而不会触发警告

  • 服务器
  • lazy
  • immediate
  • dedupe
  • watch
// ✅ This is allowed
const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: true })
const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: false })

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

// These are completely independent instances
const { data: users1 } = useAsyncData('users-1', () => $fetch('/api/users'))
const { data: users2 } = useAsyncData('users-2', () => $fetch('/api/users'))

响应式键

您可以使用计算属性、普通 ref 或 getter 函数作为键,从而实现动态数据获取,并在依赖项更改时自动更新

// Using a computed property as a key
const userId = ref('123')
const { data: user } = useAsyncData(
  computed(() => `user-${userId.value}`),
  () => fetchUser(userId.value),
)

// When userId changes, the data will be automatically refetched
// and the old data will be cleaned up if no other components use it
userId.value = '456'

刷新和执行

如果您想手动获取或刷新数据,请使用可组合函数提供的 executerefresh 函数。

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

<template>
  <div>
    <p>{{ data }}</p>
    <button @click="() => refresh()">
      Refresh data
    </button>
  </div>
</template>

execute 函数是 refresh 的别名,其工作方式完全相同,但在获取不立即时更具语义。

要全局重新获取或使缓存数据失效,请参阅 clearNuxtDatarefreshNuxtData

清除

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

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

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

监听

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

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

const { data, error, refresh } = await useFetch('/api/users', {
  /* Changing the id will trigger a refetch */
  watch: [id],
})
</script>

请注意,观察响应式值不会改变已获取的 URL。例如,这将继续获取用户的相同初始 ID,因为 URL 是在函数被调用时构建的。

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

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

如果需要根据响应式值更改 URL,您可能希望改用计算 URL

当提供了响应式获取选项时,它们将被自动监视并触发重新获取。在某些情况下,通过指定 watch: false 来选择退出此行为会很有用。

const id = ref(1)

// Won't automatically refetch when id changes
const { data, execute } = await useFetch('/api/users', {
  query: { id }, // id is watched by default
  watch: false, // disables automatic watching of id
})

// doesn't trigger refetch
id.value = 2

计算 URL

有时您可能需要根据响应式值计算 URL,并在这些值每次更改时刷新数据。您无需绞尽脑汁,而是可以将每个参数作为响应式值附加。Nuxt 将自动使用响应式值并在每次更改时重新获取。

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

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

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

每当依赖项更改时,都会使用新构建的 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>
    <!-- disable the input while fetching -->
    <input
      v-model="id"
      type="number"
      :disabled="pending"
    >

    <div v-if="status === 'idle'">
      Type an user ID
    </div>

    <div v-else-if="pending">
      Loading ...
    </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">
      Get data
    </button>
  </div>

  <div v-else-if="status === 'pending'">
    Loading comments...
  </div>

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

为了更精细的控制,status 变量可以是

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

传递头和 Cookie

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

通常,在服务器端渲染期间,出于安全考虑,$fetch 不会包含用户的浏览器 cookie,也不会传递来自 fetch 响应的 cookie。

然而,当在服务器上使用相对 URL 调用 useFetch 时,Nuxt 将使用 useRequestFetch 代理标头和 cookie(不应转发的标头除外,例如 host)。

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

如果您想将 cookie 以另一个方向(从内部请求返回到客户端)传递/代理,则需要自行处理。

app/composables/fetch.ts
import { appendResponseHeader } from 'h3'
import type { H3Event } from 'h3'

export const fetchWithCookie = async (event: H3Event, url: string) => {
  /* Get the response from the server endpoint */
  const res = await $fetch.raw(url)
  /* Get the cookies from the response */
  const cookies = res.headers.getSetCookie()
  /* Attach each cookie to our incoming Request */
  for (const cookie of cookies) {
    appendResponseHeader(event, 'set-cookie', cookie)
  }
  /* Return the data of the response */
  return res._data
}
<script setup lang="ts">
// This composable will automatically pass cookies to the client
const event = useRequestEvent()

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

onMounted(() => console.log(document.cookie))
</script>

选项 API 支持

Nuxt 提供了在 Options API 中执行 asyncData 获取的方法。为此,您必须将组件定义封装在 defineNuxtComponent 中。

<script>
export default defineNuxtComponent({
  /* Use the fetchKey option to provide a unique key */
  fetchKey: 'hello',
  async asyncData () {
    return {
      hello: await $fetch('/api/hello'),
    }
  },
})
</script>
使用 <script setup><script setup lang="ts"> 是在 Nuxt 中声明 Vue 组件的推荐方式。
文档 > 4 X > API > Utils > Define Nuxt Component 中阅读更多信息。

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

当使用 useAsyncDatauseLazyAsyncData 将在服务器上获取的数据传输到客户端(以及所有其他利用 useNuxtApp 的有效负载)时,有效负载会使用devalue进行序列化。这使我们不仅可以传输基本的 JSON,还可以序列化和复活/反序列化更高级别的数据,例如正则表达式、日期、Map 和 Set、refreactiveshallowRefshallowReactiveNuxtError 等。

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

请注意,这不适用于使用 $fetchuseFetch 从服务器路由获取的数据——有关更多信息,请参阅下一节。

从 API 路由序列化数据

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

了解更多关于 JSON.stringify 限制的信息。

示例

server/api/foo.ts
export default defineEventHandler(() => {
  return new Date()
})
app/app.vue
<script setup lang="ts">
// Type of `data` is inferred as string even though we returned a Date object
const { data } = await useFetch('/api/foo')
</script>

自定义序列化函数

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

server/api/bar.ts
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
})
app/app.vue
<script setup lang="ts">
// Type of `data` is inferred as
// {
//   createdAt: {
//     year: number
//     month: number
//     day: number
//   }
// }
const { data } = await useFetch('/api/bar')
</script>

使用替代序列化器

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

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

server/api/superjson.ts
import superjson from 'superjson'

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

    // Workaround the type conversion
    toJSON () {
      return this
    },
  }

  // Serialize the output to string, using superjson
  return superjson.stringify(data) as unknown as typeof data
})
app/app.vue
<script setup lang="ts">
import superjson from 'superjson'

// `date` is inferred as { createdAt: Date } and you can safely use the Date object methods
const { data } = await useFetch('/api/superjson', {
  transform: (value) => {
    return superjson.parse(value as unknown as string)
  },
})
</script>

秘诀

通过 POST 请求消费 SSE(服务器发送事件)

如果您通过 GET 请求消费 SSE,您可以使用EventSource或 VueUse 可组合函数useEventSource.

当通过 POST 请求消费 SSE 时,您需要手动处理连接。以下是您可以如何操作:

// Make a POST request to the SSE endpoint
const response = await $fetch<ReadableStream>('/chats/ask-ai', {
  method: 'POST',
  body: {
    query: 'Hello AI, how are you?',
  },
  responseType: 'stream',
})

// Create a new ReadableStream from the response with TextDecoderStream to get the data as text
const reader = response.pipeThrough(new TextDecoderStream()).getReader()

// Read the chunk of data as we get it
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])