如何使用 TanStack Query 获取客户端数据
使用 TanStack Query 获取客户端数据,可选择从 Server Component 提供初始数据,并协调服务器和客户端缓存。
使用 TanStack Query 在 Client Component 中获取数据、从 Server Component 提供初始数据,并协调浏览器中的变更与缓存的服务器数据。请参阅客户端数据获取以选择模式。
设置 provider#
将使用 TanStack Query 的路由包裹在 QueryClientProvider 中。为每次服务器渲染创建一个新的 query client,并在浏览器中复用同一个 query client:
'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:
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 选项会将请求延迟到交互提供输入之后:
'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。将交互式外壳保持在边界之外,以便在结果加载期间仍可用:
'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 只能在浏览器中解析:
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>
)
}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 必须使用相同的查询键。请将键和查询选项放在一起,以便两个调用点共享相同的标识:
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,
}),
}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 状态):
'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>
}'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,以便变更可以使其失效:
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
}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 能够推迟这项工作,而不是引发当前时间预渲染错误。
当同一个变更既更新浏览器缓存又使缓存的服务器数据失效时,你可以在一个共享契约中定义这两种标识:
export const productCache = {
key: (id: string) => ['product', id] as const,
+ tag: (id: string) => `product:${id}`,
// ...
} 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 拥有浏览器副本及其重新验证。对于复用数据,请将查询键和服务器标签保存在同一个缓存契约中:
export const activityCache = {
key: ['activity', 'unread'] as const,
tag: (userId: string) => `activity:${userId}`,
}export const activityCache = {
key: ['activity', 'unread'],
tag: (userId) => `activity:${userId}`,
}在变更时,使用 useMutation 的 onMutate 回调立即更新缓存,并在写入失败时在 onError 中恢复之前的值。本示例在 action 成功后保留乐观值,因为最终值是已知的:
'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>
}'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 为缓存的服务器查询打标签,以使标签匹配:
'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))
}'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> 会在下次导航时覆盖客户端查询:
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 } : {}),
})),
}
}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>:
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>
)
}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 文档的信息。