react-admin useGetOne 数据获取 Hook 完全指南:单条记录查询、聚合优化与缓存原理
react-admin useGetOne 数据获取 Hook 完全指南:单条记录查询、聚合优化与缓存原理
本篇技术指南围绕 react-admin 核心数据获取 Hook useGetOne 展开,介绍如何在 React 组件中按 id 查询单条记录,深入讲解其参数、返回状态、react-query 缓存键机制、meta 透传与请求取消等实现细节,并给出将多个 useGetOne 聚合为 useGetManyAggregate、以及用 useReference 优雅获取引用记录的实战优化方案。读完本文,你将掌握在 react-admin 中高效、类型安全地获取并刷新单条记录的全部技能。
一、useGetOne 是什么
useGetOne 是 react-admin 在 ra-core 包中提供的核心数据获取 Hook,它在组件挂载时调用 dataProvider.getOne(),根据记录的 id 从数据提供者处查询单条记录,并返回请求的状态(加载中、成功、失败)与结果。
它是 react-admin 数据获取体系(DataFetchingGuide)中最常用的 Hook 之一,典型应用场景包括:
- 在详情展示页根据路由参数
id获取记录; - 在列表行内根据外键(如
record.userId)获取关联记录; - 在自定义页面中按需加载单条数据。
从源码结构看(packages/ra-core/src/dataProvider/useGetOne.ts),useGetOne 内部基于 TanStack Query(react-query)的 useQuery 封装,因此它天然继承了 react-query 的缓存、去重、重试、过期重取(refetch)等全部能力。其文档型注释明确描述了返回值随请求状态的变化:
- 请求开始:
{ isPending: true, isFetching: true, refetch } - 请求成功:
{ data: [来自响应的数据], isPending: false, refetch } - 请求失败:
{ error: [来自响应的错误], isPending: false, refetch }
同时,当使用相同参数第二次调用该 Hook 时,在响应返回前会先返回缓存结果(stale-while-revalidate 模式)。
二、语法与参数
const { data, isPending, error, refetch } = useGetOne(
resource,
{ id, meta },
options
);
三个参数说明如下:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
resource |
string |
是 | 资源名,例如 'users'、'posts',须与 <Resource> 组件声明的资源名一致 |
params |
{ id, meta } |
是 | 查询参数对象:id 为记录标识符;meta 可选,可以是任意你想传给数据提供者的内容 |
options |
object |
否 | 透传给 react-query useQuery 的选项对象 |
从类型定义看(packages/ra-core/src/types.ts),GetOneParams 的结构为:
export interface GetOneParams<RecordType extends RaRecord = any> {
id: RecordType['id'];
meta?: any;
signal?: AbortSignal;
}
其中 signal 是 useGetOne 在内部注入的 AbortSignal(当数据提供者声明支持取消时),通常无需手动传入。数据提供者的 getOne() 方法返回 GetOneResult:{ data: RecordType, meta?: any },而 useGetOne 会把 data 直接解包返回,因此你拿到的 data 就是记录本身。
meta 参数
meta 是可选参数,可携带任何你要传给数据提供者的附加信息,例如要返回的字段列表、请求的扩展参数等。数据提供者会在 getOne(resource, { id, meta, signal }) 中收到它,可用于后端字段裁剪或自定义逻辑。
options 参数
options 可选,直接透传给 react-query 的 useQuery,支持以下选项(完整列表来自 useGetOne.md):
cacheTimeenabledinitialDatainitialDataUpdatedAtisDataEqualkeepPreviousDatametanotifyOnChangePropsnotifyOnChangePropsExclusionsonErroronSettledonSuccessplaceholderDataqueryKeyHashFnrefetchIntervalrefetchIntervalInBackgroundrefetchOnMountrefetchOnReconnectrefetchOnWindowFocusretryretryOnMountretryDelayselectstaleTimestructuralSharingsuspenseuseErrorBoundary
其中 enabled 在 useGetOne 中有特殊默认行为:从源码看(useGetOne.ts),其生效条件为 enabled ?? id != null,即当 id 为 null 或 undefined 时,查询默认不会执行。这在"记录尚未加载完毕、外键还为空"的场景下非常实用,可避免向数据提供者发起无效请求。
此外,onSuccess、onError、onSettled 三个副作用回调在 useGetOne 中被内部包装为稳定事件处理器(useEvent),并通过 useEffect 精确触发,确保它们只在对应状态发生且请求非刷新中(isFetching)时才被调用,避免因回调引用变化引发的重复执行。
三、查询键(Query Key)
useGetOne 使用的 react-query 查询键为:
[resource, 'getOne', { id: String(id), meta }]
也就是说,例如 useGetOne('users', { id: 123 }) 的查询键是 ['users', 'getOne', { id: '123' }]。
源码中有一个值得注意的细节(useGetOne.ts):id 在进入查询键之前会被强制转为字符串(String(id))。注释说明了原因:
有时
id来自字符串(例如在 Show 视图中从 URL 读取),有时来自数字(例如从useGetList返回的 Record 中读取)。由于 react-query 缓存对类型敏感,我们总是将标识符字符串化以获得匹配。
这意味着 useGetOne('posts', { id: 1 }) 与 useGetOne('posts', { id: '1' }) 共享同一个缓存条目,并且与 useGetList、useGetMany 等 Hook 写入的缓存可以互通(因为它们使用同样的字符串化约定),为跨 Hook 的缓存复用打下基础。理解这一点有助于调试"缓存未命中"类问题。
四、基本用法
在组件中调用 useGetOne 即可按 id 查询单条记录。以下示例在记录上下文中读取外键,再查询对应的用户:
import { useGetOne, useRecordContext } from 'ra-core';
const UserProfile = () => {
const record = useRecordContext();
const { data: user, isPending, error } = useGetOne('users', { id: record.userId });
if (isPending) { return <div>Loading...</div>; }
if (error) { return <p>ERROR</p>; }
return <div>User {user.username}</div>;
};
注意需要将组件包裹在 <AdminContext> / <CoreAdminContext>(或 <Admin>)中,useGetOne 才能通过 useDataProvider() 拿到数据提供者。在 react-admin 的标准页面(List / Show / Edit)内,useRecordContext() 会自动提供当前记录。
对应的单元测试(packages/ra-core/src/dataProvider/useGetOne.spec.tsx)验证了以下关键行为,可作为理解 Hook 语义的依据:
- 挂载时调用一次
dataProvider.getOne()(测试should call dataProvider.getOne() on mount); enabled: false时不发起请求,置回true后才会调用(测试should not call dataProvider.getOne() on mount if enabled is false);- 组件重新渲染不重复请求(测试
should not call dataProvider.getOne() on update); id变化会重新请求(测试should recall dataProvider.getOne() when id changes);resource变化会重新请求(测试should recall dataProvider.getOne() when resource changes);meta会原样传给数据提供者(测试should accept a meta parameter,断言调用参数为{ id: 1, meta: { hello: 'world' }, signal: undefined });- 请求失败时
error状态被正确设置(测试should set the error state when the dataProvider fails)。
请求取消(AbortSignal)支持
源码显示(useGetOne.ts),当数据提供者设置了 dataProvider.supportAbortSignal === true 时,useGetOne 会把 react-query 的 signal 透传给 getOne(resource, { id, meta, signal });否则传 undefined。对应的测试(should abort the request if the query is canceled)通过 queryClient.cancelQueries({ queryKey: ['posts', 'getOne', { id: '1' }] }) 验证了取消请求时 abort 会被触发。这意味着:只要你的数据提供者实现了基于 signal 的取消逻辑(例如基于 fetch 的 AbortController),切换到其他页面或组件卸载时请求可被及时中断。
五、聚合多个 getOne 调用:useGetManyAggregate
当页面上针对同一资源多次使用 useGetOne 时(例如在列表的每一行都渲染一个 <UserProfile>),每条记录都会触发一次 dataProvider.getOne(),造成大量重复请求。此时应改用 useGetManyAggregate,它会把对单条记录的多次查询去重并聚合成一次批量查询(dataProvider.getMany())。
-import { useGetOne, useRecordContext } from 'ra-core';
+import { useGetManyAggregate, useRecordContext } from 'ra-core';
const UserProfile = () => {
const record = useRecordContext();
- const { data: user, isPending, error } = useGetOne('users', { id: record.userId });
+ const { data: users, isPending, error } = useGetManyAggregate('users', { ids: [record.userId] });
if (isPending) { return <div>Loading...</div>; }
if (error) { return <p>ERROR</p>; }
- return <div>User {user.username}</div>;
+ return <div>User {users[0].username}</div>;
};
例如,若上面的 <UserProfile> 组件在列表上下文中被渲染多次,整个列表只会发出一次 dataProvider.getMany() 请求,而不是每行一次 getOne()。
从源码看(packages/ra-core/src/dataProvider/useGetManyAggregate.ts),聚合的实现非常巧妙:
- 内部通过
batch()函数(setTimeout(..., 0)延迟合并)把同一 tick 内的多次调用收集起来; - 按
resource|meta分组,再用union合并去重ids; - 最终只调用一次
dataProvider.getMany(uniqueResource, { ids: aggregatedIds, meta }),并把返回数据按各自请求的ids拆分、分别 resolve 给每个useQuery; - 在成功回调中还会把每条记录乐观写回
getOne缓存(queryClient.setQueryData([resource, 'getOne', { id: String(record.id), meta }], ...)),使得后续useGetOne调用可以直接命中缓存。
该 Hook 同样支持通过 options.enabled 控制是否执行,且当 ids 为空时不会调用数据提供者,直接返回空数组。
六、更语义化的选择:useReference
由于 useGetManyAggregate 经常被用来获取引用记录,ra-core 额外暴露了 useReference Hook。它属于应用级 Hook(而非数据提供者级 Hook),帮你免去手动构造 ids: [id] 数组、再从数组中取 data[0] 的样板代码,因此在"用 useGetOne 获取一条引用记录"的场景下,优先使用 useReference:
-import { useGetOne, useRecordContext } from 'ra-core';
+import { useReference, useRecordContext } from 'ra-core';
const UserProfile = () => {
const record = useRecordContext();
- const { data: user, isPending, error } = useGetOne('users', { id: record.userId });
+ const { referenceRecord: user, isPending, error } = useReference({ reference: 'users', id: record.userId });
if (isPending) { return <Loading />; }
if (error) { return <p>ERROR</p>; }
return <div>User {user.username}</div>;
};
源码实现(packages/ra-core/src/controller/useReference.ts)显示,useReference 接收 { reference, id, options },内部调用 useGetManyAggregate(reference, { ids: <a href="https://link.gitcode.com/i/f9394ad5e6672685e5dda3bf63bbae5f" target="_blank">id], meta }, options),并返回解包后的 referenceRecord(即 data ? data[0] : undefined),同时透传 refetch、error、isPending、isLoading、isFetching 等状态。其测试文件见 [packages/ra-core/src/controller/useReference.spec.tsx。
三个 Hook 的选择建议总结如下:
| 场景 | 推荐 Hook |
|---|---|
| 单处按 id 查询一条记录 | useGetOne |
| 同一资源多处按 id 查询(列表行内取引用) | useGetManyAggregate |
| 查询引用记录(外键关联) | useReference |
七、刷新记录:refetch
useGetOne(以及 useGetManyAggregate、useReference)返回的 refetch 函数可用来手动重新发起查询、刷新记录:
import { useGetOne } from 'ra-core';
const UserProfile = ({ userId }) => {
const { data, isPending, error, refetch } = useGetOne('users', { id: userId });
if (isPending) { return <div>Loading...</div>; }
if (error) { return <p>ERROR</p>; }
return (
<>
<div>User {data.username}</div>
<button onClick={() => refetch()}>Refresh</button>
</>
);
};
除手动 refetch 外,配合 options 中的 refetchInterval(轮询)、refetchOnWindowFocus(窗口聚焦时刷新)、staleTime(数据新鲜期)等 react-query 选项,可以精确控制记录的自动刷新策略。值得注意的是,当某个 useGetManyAggregate 请求成功后,它会同时填充 getOne 缓存,因此对同一条记录的 useGetOne 后续调用可能直接命中缓存而不重新请求——若你需要强制最新数据,请使用 refetch()。
八、TypeScript 类型支持
useGetOne 接受泛型参数来标注记录类型,返回的 data 会被推断为该类型:
import { useGetOne, useRecordContext } from 'ra-core';
type Ticket = {
id: number;
userId: string;
message: string;
};
type User = {
id: number;
username: string;
}
const UserProfile = () => {
const ticket = useRecordContext<Ticket>();
const { data: user, isPending, error } = useGetOne<User>('users', { id: ticket.userId });
if (isPending) { return <div>Loading...</div>; }
if (error) { return <p>ERROR</p>; }
// TypeScript 知道 user 是 User 类型
return <div>User {user.username}</div>;
};
从类型定义看(useGetOne.ts),useGetOne<RecordType, ErrorType> 支持两个泛型:RecordType extends RaRecord(记录类型,默认 any)与 ErrorType(错误类型,默认 Error)。其返回值类型为 UseQueryResult<GetOneResult<RecordType>['data'], ErrorType>,即 react-query 的标准查询结果。测试(useGetOne.spec.tsx 的 TypeScript 描述块)还验证了"id 可以为空(如 comment?.post_id)"的场景——此时查询不会执行,data 类型仍正确推断,方便在数据未就绪时安全使用。
九、总结
useGetOne在组件挂载时调用dataProvider.getOne(),按id返回单条记录,并基于 react-query 提供缓存、重试、取消与自动刷新能力;- 查询键固定为
[resource, 'getOne', { id: String(id), meta }],id统一字符串化以保证跨 Hook 缓存互通; options支持 react-queryuseQuery的完整选项列表,其中enabled默认与id != null联动,空id不发起请求;- 页面多处查询同一资源时,改用
useGetManyAggregate(同 tick 内聚合成一次getMany并写回getOne缓存)或useReference(面向引用记录的语义化封装)以减少数据提供者调用次数; - 通过返回的
refetch可随时手动刷新记录;配合泛型可获得完整的 TypeScript 类型推导。
若想进一步了解数据提供者如何实现 getOne,可参考 DataProviderWriting、DataProviderList 与 DataFetchingGuide;完整的 Hook 列表见 useGetOne.md 同目录下的其他文档,以及 ra-core 的 dataProvider 模块。