这篇翻译之后英文原文有更新,内容可能已过时。
从 TanStack Query 迁移
TanStack Query(React Query)会单独缓存每个查询键的响应,因此应用要靠在每次变更后让这些键失效来保持它们一致。Reactive Data Client 会把响应规范化为 Entity:变更的响应会更新所有展示该 Entity 的列表和详情,大部分失效代码也就不再需要了。
迁移会用类型化的 endpoint 替换查询函数和键,用 useSuspense()
和 Controller 调用替换 hook,用 DataProvider 替换 QueryClient。步骤给出了顺序;API 对照表给出了每个 TanStack Query API 的替代方案。
用你的编程 agent 迁移
把下面的内容粘贴到 agent 的对话框中:
setup skill 遵循本指南。像审查队友的代码一样审查它的 diff。
步骤
每完成一步,都要保证应用的测试通过;它们能证明行为没有改变。
- Endpoint 和 schema。 把每个查询函数和变更函数变成一个 endpoint:按照这些函数所调用的 HTTP 库(axios、fetch、ky)对应的 REST 配置操作,然后为每个 endpoint 提供一个由 Entity 构建的
schema。没有 schema 就不会进行任何规范化,你也就需要保留每一处invalidateQueries调用。把 Entity 和 endpoint 放在一个所有功能模块都能导入的文件夹中(比如src/resources/),而不是放在各功能模块的api/文件夹中,即使查询 hook 原来就在那里:一个功能模块中的变更经常会更新另一个功能模块的 Entity。如果 lint 规则限制了文件夹之间的导入(import/no-restricted-paths、eslint-plugin-boundaries、Nx 模块边界),请使用它们允许的共享层。 - Provider。 用
DataProvider替换QueryClientProvider(Provider)。 - 读取。 在渲染数据的组件中,用
useSuspense()替换useQuery()和useSuspenseQuery()(读取)。 - 变更。 用
ctrl.fetch()替换useMutation(),并删除因规范化而变得不再需要的失效代码(变更)。 - Loader 和预取。 在路由 loader 和悬停预取中,用
ctrl.fetchIfStale()替换queryClient(Loader 和预取)。 - 无限查询。 用 Collection 和
getPage替换useInfiniteQuery()(无限查询)。 - 身份认证。 替换基于 TanStack Query 构建的身份认证库,比如
react-query-auth(身份认证)。 - 测试。 替换测试 wrapper 中的
QueryClientProvider,以及对加载指示器的假设(测试)。 - 清理。 删除查询键工厂、
queryOptions()辅助函数以及类似lib/react-query.ts的配置。当没有文件再导入@tanstack/react-query和@tanstack/react-query-devtools时,卸载它们。
这些步骤会保留应用的行为,除非 Data Client 能用更少的代码修复它:变更后仍显示过时数据的列表、变更后的重新获取,以及为列表已加载的条目发出的请求。需要额外代码或改变用户所见内容的改动(比如添加应用原本没有的乐观更新)属于单独的、可选的性能优化检查。请先完成并检查迁移,这样你就能衡量每个阶段。
API 对照表
| TanStack Query | Data Client |
|---|---|
queryFn + queryKey、queryOptions() | 一个带有 schema 的 endpoint。endpoint 及其参数就是键,因此不再需要键工厂 |
useQuery()、useSuspenseQuery() | useSuspense(endpoint, args):加载状态交给最近的 <Suspense>,错误交给最近的 Error Boundary,并且 data 永远不会是 undefined |
组件自己渲染加载指示器或错误的 useQuery() | useDLE():{ data, loading, error } |
enabled: false | 用 null 代替参数:useSuspense(endpoint, id ? { id } : null) 返回 undefined,且不获取任何东西 |
select | 在渲染中计算,或使用通过 useQuery() 读取的 Query schema |
useQueries() | 对每一个使用 useFetch(),再使用 React 的 use():它们会并行获取 |
staleTime | endpoint 或基类上的 dataExpiryLength。默认为 60 秒(TanStack Query 的默认值为 0) |
gcTime | DataProvider 的 gcPolicy |
retry | 删除它:Data Client 没有重试循环。出错的请求会在 errorExpiryLength(默认 1 秒)之后、有组件需要它时再次获取,类似 TanStack Query 的 retry: false |
refetchInterval | endpoint 上的 pollFrequency,通过 useLive() 读取 |
refetchOnWindowFocus | 删除它:Data Client 不会在窗口获得焦点时重新获取 |
placeholderData: keepPreviousData | 在 startTransition() 中修改参数(对于输入框则使用 useDebounce()):React 会在下一份数据加载期间继续展示当前数据 |
来自列表查询的 initialData | 删除它:当详情 endpoint 的 schema 是该 Entity 时,只要列表的数据仍然新鲜,列表加载过的 Entity 就会在详情页直接渲染,无需获取 |
useMutation() | 在事件处理函数中调用来自 useController() 的 ctrl.fetch(endpoint, ...args) |
变更的 isPending、error | useLoading():const [run, isPending, error] = useLoading(fn, deps) |
isSuccess、onSuccess、onError | 写在 await ctrl.fetch() 之后或外围的代码(变更) |
更新后的 invalidateQueries() | 当响应就是更新后的 Entity 时,删除它 |
创建后的 invalidateQueries() | ctrl.fetch(Resource.getList.push, body)(或 unshift);编号分页有所不同(变更) |
删除后的 invalidateQueries() | 删除它:resource().delete(或 schema.Invalidate schema)会把该 Entity 从每个列表中移除 |
针对响应中未包含的数据(计数、总计)的 invalidateQueries() | ctrl.expireAll(endpoint):已挂载的组件会重新获取 |
refetchQueries() | ctrl.fetch(endpoint, args) |
setQueryData() | ctrl.setResponse(endpoint, args, response);对于 Entity,使用 ctrl.set(Entity, args, value) |
getQueryData() | 在组件中使用 useCache()。在其他地方使用 ctrl.get(schema, args, ctrl.getState()) |
prefetchQuery() | ctrl.fetchIfStale(endpoint, args),不 await:失败永远不会产生未处理的 rejection |
ensureQueryData()、getQueryData() ?? fetchQuery() | 能渲染时使用 ctrl.getResponse() 中的缓存数据,否则使用 ctrl.fetchIfStale(endpoint, args)(Loader) |
fetchQuery() | 有 staleTime 时使用 await ctrl.fetchIfStale(endpoint, args);没有时使用 ctrl.fetch(endpoint, args) |
onMutate 乐观更新与回滚 | endpoint 上的 getOptimisticResponse():Data Client 会在出错时回滚 |
useInfiniteQuery() | 一个 Collection 和 ctrl.fetch(endpoint.getPage, args)(无限查询) |
QueryCache 或 MutationCache 上的 onError(全局错误上报) | 一个错误上报 Manager:它能看到每一次失败的 fetch |
登出时的 queryClient.clear()、removeQueries() | ctrl.resetEntireStore() |
QueryClientProvider、new QueryClient() | DataProvider |
useQueryClient() | useController() |
ReactQueryDevtools | 删除它:DataProvider 会在开发环境中添加 DevTools |
HydrationBoundary、dehydrate() | 服务端渲染 |
Data Client 自己的 useQuery() 并不是 TanStack Query 的那个。它从 store 中读取 schema,从不获取。请用 useSuspense() 或 useDLE() 替换 TanStack Query 的 useQuery()。
Provider
把 DataProvider 放在根部,位于应用的其他 provider 和 <Suspense> 边界之外,而不是放在原来
QueryClientProvider 所在的位置。它的后备边界(在开发环境中显示 "Uncaught Suspense")会先于它上方的任何边界捕获。
import { DataProvider } from '@data-client/react';
import { Suspense, type ReactNode } from 'react';
export const AppProvider = ({ children }: { children: ReactNode }) => (
<DataProvider>
<Suspense fallback={<Loading />}>{children}</Suspense>
</DataProvider>
);
DataProvider 会创建自己的 store,因此不需要创建 client。按照 API 对照表所列,把 QueryClient 的 defaultOptions 移到基础
endpoint 类中。
读取
在渲染数据的组件中调用 useSuspense(),并删除各功能模块中包装 useQuery() 的 useIssues() hook。请求相同 endpoint 和参数的两个组件会共享一次获取和一个 store 条目,因此共享 hook 没有任何好处,而且 hook 会隐藏组件的依赖。
export const issueKeys = {
all: ['issues'] as const,
list: (page: number) => [...issueKeys.all, 'list', page] as const,
detail: (id: number) => [...issueKeys.all, 'detail', id] as const,
};
export const useIssues = (page: number) =>
useQuery({ queryKey: issueKeys.list(page), queryFn: () => fetchIssues(page) });
const { data, isLoading, isError } = useIssues(page);
if (isLoading) return <TableSkeleton />;
if (isError) return <ErrorBanner />;
return <Table rows={data?.results ?? []} />;
import { useSuspense } from '@data-client/react';
import { IssueResource } from './resources/Issue';
export function IssueTable({ page }: { page: number }) {
const { results: issues, pagination } = useSuspense(IssueResource.getList, {
page,
});
return (
<table>
<caption>
Page {pagination.page} of {pagination.pageCount}
</caption>
<tbody>
{issues.map(issue => (
<tr key={issue.id}>
<td>{issue.title}</td>
<td>{issue.state}</td>
</tr>
))}
</tbody>
</table>
);
}
isLoading 分支移到 <Suspense> 的 fallback 中,isError 分支移到 Error Boundary 中;
AsyncBoundary 同时具备两者。保留应用自己的骨架屏和错误横幅作为它们的 fallback。
?? [] 防护也不再需要,因为 useSuspense() 只会在数据就绪后才返回。
同一组件中的两个 useSuspense() 调用会依次加载。当两者都不依赖对方的数据时,用
useFetch() 同时发起它们,再用 use() 读取(并行数据加载)。
信封响应
当 API 包装了响应时,比如 { "results": [...], "pagination": {...} },请在 schema 中描述这个信封,而不是把它解包,这样组件就能继续读取 pagination:
import { Entity, resource } from '@data-client/rest';
export class Issue extends Entity {
id = 0;
title = '';
state: 'open' | 'closed' = 'open';
assignee = '';
static key = 'Issue';
}
interface Pagination {
page: number;
pageCount: number;
}
export const IssueResource = resource({
path: '/issues/:id',
searchParams: {} as { page?: number },
schema: Issue,
}).extend(Base => ({
getList: Base.getList.extend({
schema: { results: [Issue], pagination: {} as Pagination },
}),
// a new issue shifts every numbered page, so this POST joins no list: callers expire it
create: Base.getList.push.extend({ schema: Issue }),
}));
searchParams 为列表的 page 参数提供类型。create 复用列表的 POST,用普通的 Issue schema 代替列表的 Collection;变更一节说明了何时使用它。当单个条目也被包装时,比如 { "data": {...} },用同样的方式扩展 get:Base.get.extend({ schema: { data: Issue } })。
变更
在应用原来调用 mutate() 的地方调用 ctrl.fetch()。onSuccess 中的逻辑放在 await 之后;onError 中的逻辑放在
catch 中。用 useLoading() 跟踪 pending 和错误状态。
export const useCloseIssue = () => {
const queryClient = useQueryClient();
return useMutation({
mutationFn: (id: number) => patchIssue(id, { state: 'closed' }),
onSuccess: issue => {
queryClient.invalidateQueries({ queryKey: issueKeys.detail(issue.id) });
toast(`Closed #${issue.id}`);
},
onError: () => toast('Could not close the issue'),
});
};
import { useController, useLoading } from '@data-client/react';
import { IssueResource } from './resources/Issue';
export function CloseIssueButton({ id }: { id: number }) {
const ctrl = useController();
const [close, isPending] = useLoading(async () => {
try {
await ctrl.fetch(IssueResource.partialUpdate, { id }, { state: 'closed' });
toast(`Closed #${id}`);
} catch {
toast('Could not close the issue');
}
}, [ctrl, id]);
return (
<button onClick={close} disabled={isPending}>
Close issue
</button>
);
}
invalidateQueries() 调用不见了:响应就是更新后的 Issue,因此表格和详情页都会显示它已关闭。TanStack Query 应用通常会让详情键失效,却不会让每个列表键失效,因此列表会显示过时的数据,直到它们过期;迁移之后就不会这样了。
根据响应决定如何处理每一处 invalidateQueries() 和 refetchQueries() 调用(更多示例见变更):
- 响应是被修改的 Entity(更新、部分更新):删除该调用,除非这次修改会让 Entity 在筛选或排序后的列表之间移动。关闭一个 issue 会在所有地方更新它,但不会把它从缓存的
?state=open列表中移除,也不会把它加入?state=closed列表;用ctrl.expireAll(Resource.getList)保持这些列表正确。 - 创建:获取列表的
push(或unshift)endpoint,而不是普通的POST,新的 Entity 就会加入每个匹配的列表。这需要列表的 schema 中有一个 Collection:resource()默认就有,而信封需要把它放在内部,比如results: new Collection([Issue])。对于拆分为编号分页的列表,新条目会让每一页发生偏移,此时请添加一个普通的POSTendpoint(即信封示例中的create:Base.getList.push.extend({ schema: Issue })),然后调用ctrl.expireAll(Resource.getList)。 - 删除:
resource().delete会把该 Entity 从每个列表中移除。对于自定义 endpoint,请使用schema: new schema.Invalidate(MyEntity)。对于拆分为编号分页的列表,还要调用ctrl.expireAll(Resource.getList):服务器上后面的条目会往前移一页,而缓存的页面无从得知。 - 响应中未包含的数据(计数、另一个资源的总计):
ctrl.expireAll(endpoint),或者在响应中返回它(副作用)。
成功状态
useLoading() 没有 isSuccess,而且它返回的函数永远不会 reject:它会把错误存起来。因此请在传给 useLoading() 的函数中、
await ctrl.fetch() 之后关闭表单或对话框,而不是在调用返回的函数之后。要保留一个成功标志:
import { useLoading } from '@data-client/react';
import { useState } from 'react';
export function useMutate<A extends unknown[]>(
mutate: (...args: A) => Promise<unknown>,
deps: readonly unknown[],
) {
const [isDone, setIsDone] = useState(false);
const [run, isPending, error] = useLoading(async (...args: A) => {
setIsDone(false);
await mutate(...args);
setIsDone(true);
}, deps);
return { run, isPending, error, isDone };
}
Loader 和预取
接收 queryClient 的路由 loader 改为接收 Controller。useController() 在每次渲染时都返回同一个
Controller,因此可以放心地用它来创建路由。
export const issueLoader =
(queryClient: QueryClient) =>
({ params }: LoaderFunctionArgs) =>
queryClient.ensureQueryData({
queryKey: issueKeys.detail(Number(params.issueId)),
queryFn: () => fetchIssue(Number(params.issueId)),
});
import { ExpiryStatus, type Controller } from '@data-client/react';
import { IssueResource } from './resources/Issue';
export const issueLoader =
(ctrl: Controller) =>
({ params }: { params: { issueId?: string } }) => {
const args = { id: Number(params.issueId) };
const { data, expiryStatus } = ctrl.getResponse(
IssueResource.get,
args,
ctrl.getState(),
);
// fetches only when missing or stale
const fetched = ctrl.fetchIfStale(IssueResource.get, args);
// like ensureQueryData(): cached data, even stale, navigates now; a miss waits for the fetch
return expiryStatus === ExpiryStatus.Valid ? data : fetched;
};
fetchIfStale() 只会在数据缺失或过时时获取,并且总是返回一个 Promise。不 await 它时,它的作用类似 prefetchQuery():失败永远不会产生未处理的 rejection,而是被存储起来供组件显示。悬停或聚焦预取也可以使用它:onMouseEnter={() => ctrl.fetchIfStale(IssueResource.get, { id })}。await 它时,它的作用类似带 staleTime 的 fetchQuery():它会 resolve 出数据(缓存数据过时时会等待重新获取),或者以该错误
reject。在 loader 原先使用 fetchQuery() 的地方使用 await 形式;在原先使用
ensureQueryData() 或 getQueryData() ?? fetchQuery() 的地方使用上面的模式。路由 loader
展示了不会让导航等待的 loader。按照 loader 之前的方式加载多个 endpoint;让页面在次要数据到达之前就显示出来,属于性能优化检查的范畴。
无限查询
useInfiniteQuery() 会保存一个页面数组。Data Client 只保存一个列表:每个新页面都会追加到其中的
Collection。在 endpoint 上设置 paginationField 即可得到它的 getPage endpoint。
import { Collection, Entity, RestEndpoint } from '@data-client/rest';
export class Note extends Entity {
id = 0;
text = '';
author = '';
static key = 'Note';
}
// every page of one issue's notes shares one list
const issueNotes = new Collection([Note], {
argsKey: ({ issueId }: { issueId: number }) => ({ issueId }),
});
export const getNotes = new RestEndpoint({
path: '/issues/:issueId/notes',
searchParams: {} as { page?: number },
schema: { results: issueNotes, nextPage: 0 as number | null },
paginationField: 'page',
});
export const addNote = new RestEndpoint({
path: '/issues/:issueId/notes',
method: 'POST',
body: {} as { text: string },
schema: issueNotes.push,
});
argsKey 省略了 page,因此每一页以及 push endpoint 都会找到同一个列表。新的笔记无需任何失效就会出现。
import { useController, useLoading, useSuspense } from '@data-client/react';
import { getNotes } from './resources/Note';
export function IssueNotes({ issueId }: { issueId: number }) {
const { results: notes, nextPage } = useSuspense(getNotes, { issueId });
const ctrl = useController();
const [loadMore, isLoadingMore] = useLoading(
async (page: number) => ctrl.fetch(getNotes.getPage, { issueId, page }),
[ctrl, issueId],
);
return (
<>
<ul>
{notes.map(note => (
<li key={note.id}>
{note.author}: {note.text}
</li>
))}
</ul>
{nextPage !== null && (
<button onClick={() => loadMore(nextPage)} disabled={isLoadingMore}>
Show older notes
</button>
)}
</>
);
}
不再需要 pages.flatMap()。getNextPageParam 计算的内容和 hasNextPage 报告的内容都来自响应(这里是 nextPage),getPage 会连同列表一起更新它。isFetchingNextPage 就是 useLoading() 的 pending 标志。关于游标,请参阅分页。
身份认证
像 react-query-auth 这样的库在 TanStack Query 之上提供了 useUser()、useLogin()、useLogout() 和 AuthLoader。用 endpoint 重新构建它们:
import { useController, useLoading, useSuspense } from '@data-client/react';
import { Entity, RestEndpoint } from '@data-client/rest';
class Account extends Entity {
id = '';
displayName = '';
static key = 'Account';
}
const getSession = new RestEndpoint({
path: '/session',
schema: { account: Account },
});
const signIn = new RestEndpoint({
path: '/session',
method: 'POST',
body: {} as { username: string; password: string },
schema: { account: Account, token: '' },
});
const signOut = new RestEndpoint({ path: '/session', method: 'DELETE' });
export const useAccount = () => useSuspense(getSession).account;
export const useSignIn = (onSuccess?: () => void) => {
const ctrl = useController();
return useLoading(
async (body: { username: string; password: string }) => {
const { account } = await ctrl.fetch(signIn, body);
// the signed-in account becomes the current one without refetching
await ctrl.setResponse(getSession, { account });
onSuccess?.();
},
[ctrl, onSuccess],
);
};
export const useSignOut = (onSuccess?: () => void) => {
const ctrl = useController();
return useLoading(async () => {
await ctrl.fetch(signOut);
await ctrl.resetEntireStore();
onSuccess?.();
}, [ctrl, onSuccess]);
};
对于注册,把 useSignIn() 复制为 useSignUp(),并换成注册 endpoint 及其 body 类型。AuthLoader 不再需要:useAccount() 会挂起到应用的 <Suspense> 边界,直到会话加载完成。这些 hook 包装的是操作,而不是数据绑定,因此值得保留为 hook。
调用处的形式会发生变化:
useUser().data变成值本身:useAccount()。useLogin({ onSuccess }).mutate(values)变成const [signIn, isPending] = useSignIn(onSuccess),然后signIn(values)。
useAccount() 需要 /session 在访客未登录时返回不含账户的响应,就像 react-query-auth 的 userFn 返回
null 一样。这样未登录的页面才能渲染,resetEntireStore() 之后的重新获取也会展示未登录状态。如果 API
返回 401,错误就会传到最近的 Error Boundary,因此请把这个状态码转换为未登录的响应:
import { Entity, NetworkError, RestEndpoint } from '@data-client/rest';
class Account extends Entity {
id = '';
displayName = '';
static key = 'Account';
}
export const getSession = new RestEndpoint({
path: '/session',
schema: { account: Account },
async fetchResponse(input: RequestInfo, init: RequestInit) {
const response = await fetch(input, init);
if (response.status === 401) {
// parseResponse() reads JSON only when the Content-Type says so
return new Response(JSON.stringify({ account: null }), {
headers: { 'Content-Type': 'application/json' },
});
}
if (!response.ok) throw new NetworkError(response);
return response;
},
});
要在任何其他 401 响应时登出,请添加 LogoutManager;关于 token 存储,请参阅身份认证。
测试
-
把测试 wrapper 中的
QueryClientProvider(以及每个测试中的new QueryClient())替换为DataProvider,并在其中放置<Suspense>。每次挂载DataProvider都会从空的 store 开始。 -
等待加载指示器消失的辅助函数在数据已经在 store 中时会失败,因为那时没有任何东西会挂起。只在存在加载指示器时才等待:
test-utils.tsimport { screen, waitForElementToBeRemoved } from '@testing-library/react';const loadingElements = () => screen.queryAllByTestId(/loading/i);export const waitForLoadingToFinish = async () => {if (loadingElements().length)await waitForElementToBeRemoved(loadingElements);}; -
Mock 服务器(MSW、
nock)无需改动即可继续工作。要在没有服务器的情况下基于 fixture 渲染,请使用 MockResolver。 -
针对查询键或
queryClient状态的断言不再需要;请对渲染出的内容进行断言。
检查迁移结果
- 没有文件导入
@tanstack/react-query,也没有残留任何queryKey、queryOptions或useQueryClient。 - 每个返回 Entity 的 endpoint 都有
schema。 - linter 通过(包括其导入边界规则),并且没有任何功能模块文件夹定义 Entity。
- 每个捕获
useSuspense()的<Suspense>或AsyncBoundary都位于DataProvider内部。 - 类型检查、单元测试和端到端测试都通过。
- 当列表返回完整的条目时,从刚加载的列表中打开某个条目不会为该条目发出请求。
- 变更之后,每个展示该 Entity 的页面无需刷新就能显示这一改动。一个在详情页编辑条目、然后返回列表的测试就能证明这一点。