Vue-Query 在 Nuxt 3 中的服务端数据获取实践

在 Nuxt 3 项目中使用 Vue-Query 进行无限滚动数据加载时，开发者可能会遇到服务端渲染(SSR)数据获取不完整的问题。本文将深入分析问题根源并提供完整的解决方案。

问题现象分析

当开发者使用 Vue-Query 的 useInfiniteQuery 进行分页数据加载时，如果直接访问目标页面，服务端能够正确获取数据。但如果从其他页面导航到目标页面，则会出现数据未获取的情况，导致客户端渲染失败。

这种现象的本质原因是 Nuxt 3 的服务端生命周期钩子 onServerPrefetch 只会在首次服务端渲染时执行。当客户端进行页面导航时，实际上是在浏览器环境中运行的单页应用(SPA)模式，此时 onServerPrefetch 不会触发。

解决方案对比

方案一：使用 useAsyncData 包装

useAsyncData(async () => {
  await suspense();
  return true;
});

这种方法利用了 Nuxt 3 提供的 useAsyncData 组合式函数，确保无论在服务端还是客户端都能正确触发数据获取。

方案二：使用 callOnce 钩子

await callOnce(async () => {
  await suspense();
});

callOnce 是 Nuxt 3 提供的专用钩子，特别适合这种只需要执行一次的数据获取场景。

最佳实践建议

1. 合理设置 staleTime
   在 Vue-Query 的全局配置中设置适当的 staleTime，可以避免数据在客户端不必要的重新获取。建议设置为大于页面渲染所需时间的值。

2. 避免直接使用 onServerPrefetch
   在 Nuxt 3 环境中，直接使用 onServerPrefetch 并不是最佳选择，因为它的行为与 Nuxt 3 的数据获取机制不完全兼容。

3. 统一数据获取方式
   无论页面是首次加载还是客户端导航，都使用相同的数据获取逻辑，可以保证一致的行为和用户体验。

实现示例

以下是一个完整的实现示例：

// 在插件中配置 Vue-Query
export default defineNuxtPlugin((nuxtApp) => {
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 1000 * 60 * 5, // 5分钟
      },
    },
  });
  
  nuxtApp.vueApp.use(VueQueryPlugin, { queryClient });
});

// 在页面组件中使用
const { data, suspense } = useInfiniteQuery({
  queryKey: ['items'],
  queryFn: fetchItems,
  getNextPageParam: (lastPage) => lastPage.nextCursor,
});

await callOnce(async () => {
  await suspense();
});

总结

在 Nuxt 3 中使用 Vue-Query 进行服务端数据获取时，开发者需要理解 Nuxt 3 的特殊生命周期和数据获取机制。通过合理使用 useAsyncData 或 callOnce 配合适当的 staleTime 配置，可以构建出既支持服务端渲染又能在客户端流畅导航的应用程序。

记住，关键在于统一服务端和客户端的数据获取行为，并确保数据在适当的时间内保持新鲜，这样才能提供最佳的用户体验。