react-admin `useGetOne` 数据获取 Hook 完全指南:从单条记录查询到查询合并与实时刷新
react-admin useGetOne 数据获取 Hook 完全指南:从单条记录查询到查询合并与实时刷新
导读
useGetOne 是 react-admin 中用于在组件挂载时调用 dataProvider.getOne()、按 id 查询单条记录的核心数据获取 Hook,广泛应用于详情展示、引用字段(ReferenceField)的底层数据加载等场景。本文基于 react-admin 官方文档与 packages/ra-core 源码,系统讲解其语法、options 参数、react-query 查询键、缓存与副作用机制,并深入剖析 useGetManyAggregate 与 useReference 的查询合并优化,以及 useGetOneLive 的实时订阅方案,帮助你写出更高效、可维护的数据获取代码。
一、useGetOne 是什么
useGetOne 是 react-admin 数据提供层(data provider 层)最基础的 Hook 之一。它封装了数据提供器(data provider)的 getOne 方法,在组件挂载时自动发起查询,并以声明式的方式返回加载状态、数据、错误与重新获取函数。
从源码看,useGetOne 定义于 packages/ra-core/src/dataProvider/useGetOne.ts,内部基于 @tanstack/react-query 的 useQuery 实现,核心职责包括:
- 在挂载时调用
dataProvider.getOne(resource, { id, meta }); - 返回请求状态对象,可按
{ data, error, isPending, refetch }解构使用; - 当以相同参数第二次调用时,在请求返回前直接返回缓存结果;
- 提供
onSuccess、onError、onSettled副作用回调(通过useEvent保证回调引用稳定,避免重复触发)。
官方测试文件 packages/ra-core/src/dataProvider/useGetOne.spec.tsx 验证了其在挂载时调用 dataProvider.getOne() 的行为,即渲染 <UseGetOne resource="posts" id={1} /> 后,getOne 被调用一次,参数为 { id: 1, signal: undefined }。
二、语法与参数详解
useGetOne 的标准调用形式如下:
const { data, isPending, error, refetch } = useGetOne(
resource,
{ id, meta },
options
);
三个参数的含义如下:
| 参数 | 类型 | 说明 |
|---|---|---|
resource |
string |
资源名称,例如 'posts'、'users' |
{ id, meta } |
对象 | id 为资源标识符(字符串或数字);meta 可选,可传入任何你想透传给数据提供器的内容,例如要返回的字段列表 |
options |
对象(可选) | 透传给 react-query 的 useQuery Hook 的配置项 |
meta 是一个值得强调的参数。它不会影响 react-query 之外的任何逻辑,而是原样透传给 dataProvider.getOne() 的第二个参数,常用于服务端字段裁剪、权限校验或自定义逻辑。测试 packages/ra-core/src/dataProvider/useGetOne.spec.tsx 表明,传入 meta={{ hello: 'world' }} 后,getOne 收到的参数为 { id: 1, meta: { hello: 'world' }, signal: undefined }。
注意:
options中的meta与第二个参数{ id, meta }中的meta不同。react-query 的useQuery也接受meta选项,用于标记查询(例如配合 devtools 使用),而查询请求透传的meta应放在第二个参数中。
三、options 完整配置清单
options 参数是可选的,会透传给 react-query 的 useQuery Hook。react-admin 官方文档列出了以下可选项:
cacheTimeenabledinitialDatainitialDataUpdatedAtisDataEqualkeepPreviousDatametanotifyOnChangePropsnotifyOnChangePropsExclusionsonErroronSettledonSuccessplaceholderDataqueryKeyHashFnrefetchIntervalrefetchIntervalInBackgroundrefetchOnMountrefetchOnReconnectrefetchOnWindowFocusretryretryOnMountretryDelayselectstaleTimestructuralSharingsuspenseuseErrorBoundary
其中几个高频选项的典型用法:
const { data, isPending, error, refetch } = useGetOne(
'users',
{ id: record.userId },
{
enabled: Boolean(record.userId), // 条件查询,id 未就绪时不发起请求
staleTime: 60_000, // 60 秒内视为新鲜数据,不重新请求
retry: 3, // 失败重试次数
onSuccess: data => notify(`加载成功:${data.username}`),
onError: err => notify(`加载失败:${err.message}`, { type: 'error' }),
refetchOnWindowFocus: false, // 窗口聚焦时是否重新请求
}
);
需要特别说明的是 enabled 的默认行为:从源码 useGetOne.ts 可见,当未显式传入 enabled 时,其默认值为 id != null。也就是说:
- 若
id为undefined或null,查询默认不会发起; - 同时,
queryFn内部也会在id == null时Promise.reject('useGetOne: id cannot be null')做双重保护。
测试 useGetOne.spec.tsx 验证了 enabled: false 时不发起请求、改为 enabled: true 后重新渲染即发起请求的行为。
options 的类型约束:UseGetOneOptions 通过 Omit<UseQueryOptions<GetOneResult<RecordType><a href="https://link.gitcode.com/i/721c74f611b36bd51141649b3787f216" target="_blank">'data'], ErrorType>, 'queryKey' | 'queryFn'> 定义了类型,即不允许覆盖 queryKey 与 queryFn(这两者由 react-admin 内部控制),并额外提供了类型安全的 onSuccess、onError、onSettled 签名,详见 [useGetOne.ts。
四、查询键(Query Key)与缓存机制
useGetOne 的 react-query 查询键(query key)为:
[resource, 'getOne', { id: String(id), meta }]
这是一个值得深入理解的细节。源码 useGetOne.ts 中的注释解释了原因:
有时
id以字符串形式出现(例如在 Show 视图中从 URL 读取),有时以数字形式出现(例如从useGetList响应中的 Record 读取)。由于 react-query 的缓存对类型敏感,因此始终将标识符字符串化以保证缓存匹配。
也就是说,无论传入 id: 1 还是 id: '1',最终查询键都是 ['posts', 'getOne', { id: '1', meta }],这确保了:
- 不同组件用
1和'1'查询同一条记录时,能够命中同一个缓存条目; - 当其他 Hook(例如
useGetList、useGetManyAggregate)写入了同键缓存时,useGetOne能直接复用。
配合 staleTime 与 cacheTime,useGetOne 拥有完整的缓存能力:组件卸载后记录仍保留在缓存中,下次挂载时立即返回缓存数据(isPending: false),再按需在后台重新验证。这一行为在源码注释(useGetOne.ts)中也有明确说明。
五、基础使用示例
在组件中调用 useGetOne,即可按 id 查询单条记录:
import { useGetOne, useRecordContext } from 'react-admin';
const UserProfile = () => {
const record = useRecordContext();
const { data: user, isPending, error } = useGetOne('users', { id: record.userId });
if (isPending) { return <Loading />; }
if (error) { return <p>ERROR</p>; }
return <div>User {user.username}</div>;
};
该组件通常在父级数据上下文中渲染(例如在 <Datagrid>、<Show> 或 <ReferenceField> 内部),通过 useRecordContext 拿到当前记录,再用 record.userId 发起对 users 资源单条记录的查询。
六、聚合 getOne 调用:useGetManyAggregate 与 useReference
当同一页面上对同一资源多次使用 useGetOne 时(典型的场景是列表的每一行都要展示一条关联记录),会产生大量 getOne 请求。官方文档建议此时改用 useGetManyAggregate,因为它会对单条记录查询做去重与聚合,将多次单条查询合并为一次批量查询。
6.1 改用 useGetManyAggregate
-import { useGetOne, useRecordContext } from 'react-admin';
+import { useGetManyAggregate, useRecordContext } from 'react-admin';
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 <Loading />; }
if (error) { return <p>ERROR</p>; }
- return <div>User {user.username}</div>;
+ return <div>User {users[0].username}</div>;
};
效果是显著减少对数据提供器的调用次数。例如,如果上面的 <UserProfile> 组件渲染在 <DataTable> 中,改造后整张列表只需调用一次 dataProvider.getMany(),而不是每行一次 dataProvider.getOne()。
6.2 源码级剖析:聚合是如何实现的
useGetManyAggregate 的实现位于 packages/ra-core/src/dataProvider/useGetManyAggregate.ts。其聚合机制值得展开:
- 批量调用(batch):所有同一 tick 内的
useGetManyAggregate调用会被batch()函数收集,通过setTimeout(..., 0)合并为一次执行,见源码 useGetManyAggregate.ts; - 按资源与 meta 分组:合并执行时,调用按
${resource}|${JSON.stringify(meta)}分组(见 useGetManyAggregate.ts),确保不同资源或不同meta的查询不会被错误合并; - id 去重合并:同一组内的
ids通过union去重合并,例如调用useGetManyAggregate('tags', [1, 2, 3])与useGetManyAggregate('tags', [3, 4])会被合并为一次dataProvider.getMany('tags', [1, 2, 3, 4]); - 结果分发:通过
notifyManager.batch()在单次事务内写入所有 pending 查询的数据,避免大量子组件在提交阶段产生嵌套更新而触发 “Maximum update depth exceeded” 报错,见 useGetManyAggregate.ts 的详细注释。
此外,useGetManyAggregate 还有一个巧妙设计:它会用 getOne 缓存作为 placeholderData(见 useGetManyAggregate.ts),并在批量查询返回后反向填充 getOne 缓存(见 useGetManyAggregate.ts)。这意味着 getMany 与 getOne 两个 Hook 共享同一份记录缓存,后续任何 useGetOne 调用都能立即命中。
6.3 优先使用 useReference
由于 useGetManyAggregate 常用于获取引用(reference)记录,react-admin 额外封装了 useReference Hook,省去了手动进行数组转换的麻烦。它是一个应用层 Hook(而不是数据提供层 Hook),语法略有不同,源码位于 packages/ra-core/src/controller/useReference.ts。
-import { useGetOne, useRecordContext } from 'react-admin';
+import { useReference, useRecordContext } from 'react-admin';
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>;
};
从实现上看,useReference 内部正是调用了 useGetManyAggregate(reference, { ids: <a href="https://link.gitcode.com/i/07b197528486325618be213594574d76" target="_blank">id], meta }),并将返回的数组首元素作为 referenceRecord 暴露出来([useReference.ts)。因此,当你使用 useGetOne 获取的是一条引用记录时,官方推荐优先改用 useReference,从而自动获得批量查询去重带来的性能收益。
七、刷新记录:refetch
当你需要手动刷新记录时,使用 Hook 返回的 refetch 函数:
import { useGetOne } from 'react-admin';
const UserProfile = ({ userId }) => {
const { data, isPending, error, refetch } = useGetOne('users', { id: userId });
if (isPending) { return <Loading />; }
if (error) { return <p>ERROR</p>; }
return (
<>
<div>User {data.username}</div>
<button onClick={() => refetch()}>Refresh</button>
</>
);
};
点击 Refresh 按钮后,useGetOne 会重新调用 dataProvider.getOne() 并更新数据。此外,refetch 也可在副作用中调用,例如配合通知或定时任务使用。
八、实时更新:useGetOneLive
如果需要订阅记录的实时更新(主题 resource/<a href="https://link.gitcode.com/i/87443eb1ad9947228d2f54dac76b43ce" target="_blank">resource]/[id]),请改用 useGetOneLive Hook 替代 useGetOne。useGetOneLive 属于 Enterprise Edition(企业版)的 @react-admin/ra-realtime 包,其详细文档见 [useGetOneLive.md。
-import { useGetOne, useRecordContext } from 'react-admin';
+import { useRecordContext } from 'react-admin';
+import { useGetOneLive } from '@react-admin/ra-realtime';
const UserProfile = () => {
const record = useRecordContext();
- const { data, isPending, error } = useGetOne('users', { id: record.userId });
+ const { data, isPending, error } = useGetOneLive('users', { id: record.userId });
if (isPending) {
return <Loading />;
}
if (error) {
return <p>ERROR</p>;
}
return <div>User {data.username}</div>;
};
根据 useGetOneLive.md,该 Hook 会订阅记录上的实时更新,并在记录被更新或删除时自动重新获取。其参数与返回类型与 useGetOne 保持一致,区别仅在于数据源的实时性。
九、TypeScript 泛型支持
useGetOne 接受一个记录类型的泛型参数,使返回值获得完整的类型推断:
import { useGetOne, useRecordContext } from 'react-admin';
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 <Loading />; }
if (error) { return <p>ERROR</p>; }
// TypeScript 已经知道 user 的类型是 User
return <div>User {user.username}</div>;
};
useGetOne 的完整类型签名(useGetOne.ts)为:
export const useGetOne = <RecordType extends RaRecord = any, ErrorType = Error>(
resource: string,
{ id, meta }: Partial<GetOneParams<RecordType>>,
options: UseGetOneOptions<RecordType, ErrorType> = {}
): UseGetOneHookValue<RecordType, ErrorType>
其中返回类型 UseGetOneHookValue 即 UseQueryResult<GetOneResult<RecordType><a href="https://link.gitcode.com/i/e46144b7f935d970c4f7d362db554cbe" target="_blank">'data'], ErrorType>,也就是标准的 react-query 结果对象([useGetOne.ts)。测试文件 useGetOne.spec.tsx 也覆盖了泛型类型的编译期校验。
十、底层行为与最佳实践小结
结合源码 useGetOne.ts 的注释,useGetOne 的返回值随请求状态变化:
- 开始:
{ isPending: true, isFetching: true, refetch } - 成功:
{ data: [响应数据], isPending: false, refetch } - 失败:
{ error: [响应错误], isPending: false, refetch }
基于以上分析,归纳出以下最佳实践:
- 列表内多条引用查询优先用
useGetManyAggregate或useReference:它们自动聚合去重,一个页面内多次引用同一资源时只需一次getMany请求; - 善用
enabled控制查询时机:当id来自异步上下文(如另一个查询的结果)时,可显式传入enabled,避免无谓请求;默认行为是id == null时不请求; - 利用统一的查询键缓存:
[resource, 'getOne', { id: String(id), meta }]使getOne与getMany共享缓存,可配合staleTime、cacheTime调节新鲜度与缓存保留时长; - 副作用回调使用
onSuccess/onError/onSettled:它们通过useEvent保持引用稳定,适合触发通知、刷新等其他 UI 行为; - 需要实时更新时切换到
useGetOneLive:当业务要求记录在服务端变更时前端自动刷新,使用@react-admin/ra-realtime提供的实时 Hook; - 为记录声明 TypeScript 泛型:让
data获得精确类型,减少运行时防御性判断。
延伸阅读
- useGetOneLive.md:支持实时订阅的单条记录查询 Hook
- useGetManyAggregate 源码:批量查询聚合的完整实现
- useReference 源码:获取引用记录的应用层 Hook
- useGetOne 单元测试:覆盖挂载调用、enabled、缓存、错误处理、副作用与 abort 等行为的测试用例
- useGetOneLive.md 对应的 Realtime 数据提供器文档 与 Realtime 总览,可了解实时数据链路
- useDataProvider 文档:了解 Hook 底层所依赖的数据提供器上下文