NNext.js 中文网 GitHub

如何使用 TanStack Query 获取客户端数据

使用 TanStack Query 获取客户端数据,可选择从 Server Component 提供初始数据,并协调服务器和客户端缓存。

使用 TanStack Query 在 Client Component 中获取数据、从 Server Component 提供初始数据,并协调浏览器中的变更与缓存的服务器数据。请参阅客户端数据获取以选择模式。

设置 provider#

将使用 TanStack Query 的路由包裹在 QueryClientProvider 中。为每次服务器渲染创建一个新的 query client,并在浏览器中复用同一个 query client:

app/products/providers.tsx
'use client'

import type { ReactNode } from 'react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

let browserQueryClient: QueryClient | undefined

function getQueryClient() {
  // 保持服务器请求相互隔离,并在多次渲染之间保留浏览器缓存。
  if (typeof window === 'undefined') return new QueryClient()
  browserQueryClient ??= new QueryClient()
  return browserQueryClient
}

export function Providers({ children }: { children: ReactNode }) {
  return (
    <QueryClientProvider client={getQueryClient()}>
      {children}
    </QueryClientProvider>
  )
}

从最近的共享布局中渲染该 provider:

app/products/layout.tsx
import { Providers } from './providers'

export default function Layout({ children }: LayoutProps<'/products'>) {
  return <Providers>{children}</Providers>
}

请参阅演示源码中完整的 provider 设置,或在 TanStack Query 高级 SSR 指南中了解 provider 选项。

在客户端获取数据#

当初始视图可以等待 hydration 之后的浏览器请求时,TanStack Query 可以完全在浏览器中获取数据。根据加载 UI 应出现的位置,选择内联或 Suspense 加载状态。在这些示例中,query 初始为空,并在 hydration 后根据客户端状态更新。

当组件应自行渲染加载和错误状态时,使用 useQuery。enabled 选项会将请求延迟到交互提供输入之后:

app/product-autocomplete.tsx
'use client'

import { useQuery } from '@tanstack/react-query'

type Product = { id: string; name: string }

async function searchProducts(query: string): Promise<Product[]> {
  const response = await fetch(
    `/api/products?query=${encodeURIComponent(query)}`
  )
  if (!response.ok) throw new Error('Failed to fetch products')
  return response.json()
}

export function ProductAutocomplete({ query }: { query: string }) {
  const {
    data = [],
    error,
    isPending,
  } = useQuery({
    queryKey: ['product-search', query],
    queryFn: () => searchProducts(query),
    enabled: query.length > 0,
  })

  if (!query) return null
  if (error) return <p>Failed to load products.</p>
  if (isPending) return <p>Loading products...</p>

  return (
    <ul>
      {data.map((product) => (
        <li key={product.id}>{product.name}</li>
      ))}
    </ul>
  )
}

了解更多:TanStack Query 查询。

对客户端数据使用 Suspense#

当应由最近的 Suspense 边界定义加载 UI 时,使用 useSuspenseQuery。将交互式外壳保持在边界之外,以便在结果加载期间仍可用:

app/product-autocomplete.tsx
'use client'

import { useSuspenseQuery } from '@tanstack/react-query'
import { Suspense } from 'react'

type Product = { id: string; name: string }

async function searchProducts(query: string): Promise<Product[]> {
  const response = await fetch(
    `/api/products?query=${encodeURIComponent(query)}`
  )
  if (!response.ok) throw new Error('Failed to fetch products')
  return response.json()
}

export function ProductAutocomplete({ query }: { query: string }) {
  if (!query) return null

  return (
    <Suspense fallback={<p>Loading products...</p>}>
      <ProductResults query={query} />
    </Suspense>
  )
}

function ProductResults({ query }: { query: string }) {
  const { data } = useSuspenseQuery({
    queryKey: ['product-search', query],
    queryFn: () => searchProducts(query),
  })

  return (
    <ul>
      {data.map((product) => (
        <li key={product.id}>{product.name}</li>
      ))}
    </ul>
  )
}

如果初始请求失败,useSuspenseQuery 会将错误传播到最近的错误边界。

当查询获得数据后,同一查询的后续重新获取会继续渲染缓存的数据,而不是再次显示 Suspense 回退内容。使用 isFetching 提供后台刷新反馈。

如果初始视图需要数据,请如下所示从 Server Component 提供数据。

小知识: 一个组件中的多个 useSuspenseQuery 调用会按顺序执行。请将相互独立的查询放在兄弟组件中,或使用 useSuspenseQueries。了解更多关于请求瀑布的信息。

从 Server Component 提供初始数据#

当初始渲染需要数据,并且 TanStack Query 应继续在浏览器中管理它时,请使用服务器提供数据模式。Server Component 可以在客户端接管之前提供初始查询数据。

TanStack Query 5.40.0 或更高版本可以脱水(dehydrate)pending 状态的查询。启动 prefetchQuery 而不等待它,然后将脱水状态传递给 <HydrationBoundary>。在服务器上覆盖 queryFn,因为 Route Handler 的相对 URL 只能在浏览器中解析:

app/products/[id]/page.tsx
import { Suspense } from 'react'
import {
  defaultShouldDehydrateQuery,
  dehydrate,
  HydrationBoundary,
  QueryClient,
} from '@tanstack/react-query'
import { getProduct } from './data'
import { productCache } from './product-cache'
import { ProductView } from './product-view'

export default function Page({ params }: PageProps<'/products/[id]'>) {
  return (
    <Suspense fallback={<p>Loading…</p>}>
      {params.then(({ id }) => (
        <ProductData id={id} />
      ))}
    </Suspense>
  )
}

function ProductData({ id }: { id: string }) {
  const queryClient = new QueryClient()

  // 不等待它,因此不会阻塞渲染。
  void queryClient.prefetchQuery({
    ...productCache.options(id),
    queryFn: () => getProduct(id),
  })

  return (
    <HydrationBoundary
      state={dehydrate(queryClient, {
        shouldDehydrateQuery: (query) =>
          defaultShouldDehydrateQuery(query) ||
          query.state.status === 'pending',
      })}
    >
      <ProductView id={id} />
    </HydrationBoundary>
  )
}
app/products/[id]/page.js
import { Suspense } from 'react'
import {
  defaultShouldDehydrateQuery,
  dehydrate,
  HydrationBoundary,
  QueryClient,
} from '@tanstack/react-query'
import { getProduct } from './data'
import { productCache } from './product-cache'
import { ProductView } from './product-view'

export default function Page({ params }) {
  return (
    <Suspense fallback={<p>Loading…</p>}>
      {params.then(({ id }) => (
        <ProductData id={id} />
      ))}
    </Suspense>
  )
}

function ProductData({ id }) {
  const queryClient = new QueryClient()

  // 不等待它,因此不会阻塞渲染。
  void queryClient.prefetchQuery({
    ...productCache.options(id),
    queryFn: () => getProduct(id),
  })

  return (
    <HydrationBoundary
      state={dehydrate(queryClient, {
        shouldDehydrateQuery: (query) =>
          defaultShouldDehydrateQuery(query) ||
          query.state.status === 'pending',
      })}
    >
      <ProductView id={id} />
    </HydrationBoundary>
  )
}

服务器和 Client Component 必须使用相同的查询键。请将键和查询选项放在一起,以便两个调用点共享相同的标识:

app/products/[id]/product-cache.ts
import { queryOptions } from '@tanstack/react-query'

export type Product = { id: string; name: string }

export const productCache = {
  key: (id: string) => ['product', id] as const,
  options: (id: string) =>
    queryOptions({
      queryKey: productCache.key(id),
      queryFn: async (): Promise<Product> => {
        const res = await fetch(`/api/products/${id}`)
        if (!res.ok) throw new Error('Failed to fetch product')
        return res.json()
      },
      staleTime: 30_000,
    }),
}
app/products/[id]/product-cache.js
import { queryOptions } from '@tanstack/react-query'

export const productCache = {
  key: (id) => ['product', id],
  options: (id) =>
    queryOptions({
      queryKey: productCache.key(id),
      queryFn: async () => {
        const res = await fetch(`/api/products/${id}`)
        if (!res.ok) throw new Error('Failed to fetch product')
        return res.json()
      },
      staleTime: 30_000,
    }),
}

查询函数会获取 Route Handler 的数据,以便它可以在客户端运行。staleTime 通过让 hydration 后的数据保持 30 秒新鲜,来避免客户端立即重新获取。请根据数据变化的速度选择时长。

较大的功能可以将查询选项放在单独的面向客户端的模块中,只要每个调用方都从相同的缓存契约中导入键即可。了解更多关于 TanStack Query 默认设置的信息。

与 SWR 一样,params.then() 在 <Suspense> 内解析 id,而 ProductData 在边界下方进行预取。

Client Component 使用 useSuspenseQuery 读取相同的查询键(或使用 useQuery 以内联方式渲染 isPending 和 error 状态):

app/products/[id]/product-view.tsx
'use client'

import { useSuspenseQuery } from '@tanstack/react-query'
import { productCache } from './product-cache'

export function ProductView({ id }: { id: string }) {
  const { data } = useSuspenseQuery(productCache.options(id))

  return <h1>{data.name}</h1>
}
app/products/[id]/product-view.js
'use client'

import { useSuspenseQuery } from '@tanstack/react-query'
import { productCache } from './product-cache'

export function ProductView({ id }) {
  const { data } = useSuspenseQuery(productCache.options(id))

  return <h1>{data.name}</h1>
}

了解更多:TanStack Query 高级 SSR。

使用 Cache Components 缓存服务器提供的数据#

使用此模式前,请在 next.config.ts 中启用 cacheComponents。然后你可以缓存提供给 TanStack Query 的服务器数据。添加 use cache,选择一个 cacheLife 配置,并应用 cacheTag,以便变更可以使其失效:

app/products/[id]/data.ts
import { cacheLife, cacheTag } from 'next/cache'
import type { Product } from './product-cache'

export async function getProduct(id: string): Promise<Product> {
  'use cache'
  cacheLife('max')
  cacheTag(`product:${id}`)

  const product = await db.product.findUnique({ where: { id } })
  if (!product) throw new Error('Product not found')
  return product
}
app/products/[id]/data.js
import { cacheLife, cacheTag } from 'next/cache'

export async function getProduct(id) {
  'use cache'
  cacheLife('max')
  cacheTag(`product:${id}`)

  const product = await db.product.findUnique({ where: { id } })
  if (!product) throw new Error('Product not found')
  return product
}

本示例使用 cacheLife('max'),因为写入会使产品标签失效。在缓存配置中,stale 控制 Next.js 客户端缓存可以复用预取 payload 的时间,而 revalidate 和 expire 控制服务器缓存。当服务器上的值应随时间刷新时,请选择更短的配置。

TanStack Query 拥有独立的浏览器缓存,因此其 staleTime 无需与 cacheLife 匹配。

启用 Cache Components 后,Next.js 也会预渲染 Client Component。请将初始渲染所需的查询保持在 Suspense之后。TanStack Query 在创建活动查询状态时可以读取当前时间,而该边界让 Next.js 能够推迟这项工作,而不是引发当前时间预渲染错误。

当同一个变更既更新浏览器缓存又使缓存的服务器数据失效时,你可以在一个共享契约中定义这两种标识:

app/products/[id]/product-cache.ts
 export const productCache = {
   key: (id: string) => ['product', id] as const,
+  tag: (id: string) => `product:${id}`,
   // ...
 }
app/products/[id]/product-cache.js
 export const productCache = {
   key: (id) => ['product', id],
+  tag: (id) => `product:${id}`,
   // ...
 }

然后服务器函数可以调用 cacheTag(productCache.tag(id))。请勿在该契约中引入仅限服务器或仅限客户端的导入,以便两个缓存层都能复用它。

小知识: TanStack Query 的 dehydrate() 在 Cache Components 预渲染期间会读取当前时间。对于缓存的初始数据,请使用可预渲染的 hydration 辅助函数。

在变更后协调服务器和客户端缓存#

Hydration 提供初始的客户端缓存值。hydration 之后,TanStack Query 拥有浏览器副本及其重新验证。对于复用数据,请将查询键和服务器标签保存在同一个缓存契约中:

app/activity/activity-cache.ts
export const activityCache = {
  key: ['activity', 'unread'] as const,
  tag: (userId: string) => `activity:${userId}`,
}
app/activity/activity-cache.js
export const activityCache = {
  key: ['activity', 'unread'],
  tag: (userId) => `activity:${userId}`,
}

在变更时,使用 useMutation 的 onMutate 回调立即更新缓存,并在写入失败时在 onError 中恢复之前的值。本示例在 action 成功后保留乐观值,因为最终值是已知的:

app/activity/mark-read-button.tsx
'use client'

import { useMutation, useQueryClient } from '@tanstack/react-query'
import { markActivityReadAction } from './actions'
import { activityCache } from './activity-cache'

export function MarkReadButton() {
  const queryClient = useQueryClient()
  const queryKey = activityCache.key

  const markRead = useMutation({
    mutationFn: markActivityReadAction,
    onMutate: async () => {
      await queryClient.cancelQueries({ queryKey })
      const previous = queryClient.getQueryData(queryKey)
      queryClient.setQueryData(queryKey, { count: 0 })
      return { previous }
    },
    onError: (_error, _variables, context) => {
      queryClient.setQueryData(queryKey, context?.previous)
    },
  })

  return <button onClick={() => markRead.mutate()}>Mark read</button>
}
app/activity/mark-read-button.js
'use client'

import { useMutation, useQueryClient } from '@tanstack/react-query'
import { markActivityReadAction } from './actions'
import { activityCache } from './activity-cache'

export function MarkReadButton() {
  const queryClient = useQueryClient()
  const queryKey = activityCache.key

  const markRead = useMutation({
    mutationFn: markActivityReadAction,
    onMutate: async () => {
      await queryClient.cancelQueries({ queryKey })
      const previous = queryClient.getQueryData(queryKey)
      queryClient.setQueryData(queryKey, { count: 0 })
      return { previous }
    },
    onError: (_error, _variables, context) => {
      queryClient.setQueryData(queryKey, context?.previous)
    },
  })

  return <button onClick={() => markRead.mutate()}>Mark read</button>
}

Server Action 会写入数据库,并使用 updateTag 使带标签的服务器数据过期。请使用 cacheTag 为缓存的服务器查询打标签,以使标签匹配:

app/activity/actions.ts
'use server'

import { updateTag } from 'next/cache'
import {
  getCurrentUserId,
  markActivityRead as markActivityReadInDatabase,
} from './data'
import { activityCache } from './activity-cache'

export async function markActivityReadAction() {
  const userId = await getCurrentUserId()
  await markActivityReadInDatabase(userId)
  updateTag(activityCache.tag(userId))
}
app/activity/actions.js
'use server'

import { updateTag } from 'next/cache'
import {
  getCurrentUserId,
  markActivityRead as markActivityReadInDatabase,
} from './data'
import { activityCache } from './activity-cache'

export async function markActivityReadAction() {
  const userId = await getCurrentUserId()
  await markActivityReadInDatabase(userId)
  updateTag(activityCache.tag(userId))
}

乐观的查询值会更新当前屏幕。updateTag 确保下一次缓存的服务器读取返回最新的活动数据。

小知识: 当 Server Action 更改了必须立即反映写入的缓存读取时,请调用 updateTag。未缓存的读取没有可更新的服务器标签。有关其他失效行为,请参阅客户端数据获取。

构建可预渲染的 hydration 状态#

上面的 TanStack Query 模式使用 dehydrate() 创建 hydration 状态。使用 Cache Components 时,dehydrate() 在预渲染期间会读取当前时间(Date.now()),从而导致当前时间预渲染错误。

相反,只缓存该时间戳,并手动构建脱水状态。将时间读取包裹在 use cache 中,并使用与数据读取相同的标签。当变更使这些标签失效时,数据及其时间戳会一起推进,因此 <HydrationBoundary> 会在下次导航时覆盖客户端查询:

app/lib/hydrate.ts
import 'server-only'

import { cacheLife, cacheTag } from 'next/cache'
import {
  defaultShouldDehydrateQuery,
  QueryClient,
  type DehydratedState,
  type QueryKey,
} from '@tanstack/react-query'

type HydratedQuery = {
  queryKey: QueryKey
  data: unknown
}

type HydrationOptions = {
  tags: string[]
}

async function getHydrationUpdatedAt(tags: string[]) {
  'use cache'
  cacheTag(...tags)
  cacheLife('max')
  return Date.now()
}

export async function dehydrate(
  queries: HydratedQuery[],
  options: HydrationOptions
): Promise<DehydratedState> {
  const updatedAt = await getHydrationUpdatedAt(options.tags)

  const queryClient = new QueryClient()

  for (const query of queries) {
    queryClient.setQueryData(query.queryKey, query.data, { updatedAt })
  }

  return {
    mutations: [],
    queries: queryClient
      .getQueryCache()
      .getAll()
      .filter((query) => defaultShouldDehydrateQuery(query))
      .map((query) => ({
        dehydratedAt: updatedAt,
        queryHash: query.queryHash,
        queryKey: query.queryKey,
        state: query.state,
        ...(query.meta ? { meta: query.meta } : {}),
      })),
  }
}
app/lib/hydrate.js
import 'server-only'

import { cacheLife, cacheTag } from 'next/cache'
import { defaultShouldDehydrateQuery, QueryClient } from '@tanstack/react-query'

async function getHydrationUpdatedAt(tags) {
  'use cache'
  cacheTag(...tags)
  cacheLife('max')
  return Date.now()
}

export async function dehydrate(queries, options) {
  const updatedAt = await getHydrationUpdatedAt(options.tags)

  const queryClient = new QueryClient()

  for (const query of queries) {
    queryClient.setQueryData(query.queryKey, query.data, { updatedAt })
  }

  return {
    mutations: [],
    queries: queryClient
      .getQueryCache()
      .getAll()
      .filter((query) => defaultShouldDehydrateQuery(query))
      .map((query) => ({
        dehydratedAt: updatedAt,
        queryHash: query.queryHash,
        queryKey: query.queryKey,
        state: query.state,
        ...(query.meta ? { meta: query.meta } : {}),
      })),
  }
}

在拥有数据的段中等待该辅助函数,传入数据以及底层 getProduct 读取所使用的相同标签。将结果交给 ProductData 内的 <HydrationBoundary>:

app/products/[id]/page.tsx
import { HydrationBoundary } from '@tanstack/react-query'
import { dehydrate } from '@/app/lib/hydrate'
import { getProduct } from './data'
import { productCache } from './product-cache'
import { ProductView } from './product-view'

async function ProductData({ id }: { id: string }) {
  const product = await getProduct(id)
  const state = await dehydrate(
    [{ queryKey: productCache.key(id), data: product }],
    { tags: [productCache.tag(id)] }
  )

  return (
    <HydrationBoundary state={state}>
      <ProductView id={id} />
    </HydrationBoundary>
  )
}
app/products/[id]/page.js
import { HydrationBoundary } from '@tanstack/react-query'
import { dehydrate } from '@/app/lib/hydrate'
import { getProduct } from './data'
import { productCache } from './product-cache'
import { ProductView } from './product-view'

async function ProductData({ id }) {
  const product = await getProduct(id)
  const state = await dehydrate(
    [{ queryKey: productCache.key(id), data: product }],
    { tags: [productCache.tag(id)] }
  )

  return (
    <HydrationBoundary state={state}>
      <ProductView id={id} />
    </HydrationBoundary>
  )
}

小知识: 每当 hydration 后的数据发生变化时,时间戳都必须推进。该辅助函数适用于标签驱动的服务器数据,因为两者使用相同的标签。对于时间驱动的服务器数据,请从同一个缓存快照中派生数据和 hydration 时间戳,而不是维护互不相关的时间窗口。

请参阅在线 next-spa-patterns 演示及其源代码。了解更多关于 TanStack Query 乐观更新和 TanStack Query 文档的信息。

Next.js 中文网