react-admin `useGetOne` 数据获取 Hook 完全指南:从单条记录查询到查询合并与实时刷新

原创2026-09-20 18:59:241,661 阅读
文章标签:前端UI组件

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 官方文档列出了以下可选项:

  • cacheTime
  • enabled
  • initialData
  • initialDataUpdatedAt
  • isDataEqual
  • keepPreviousData
  • meta
  • notifyOnChangeProps
  • notifyOnChangePropsExclusions
  • onError
  • onSettled
  • onSuccess
  • placeholderData
  • queryKeyHashFn
  • refetchInterval
  • refetchIntervalInBackground
  • refetchOnMount
  • refetchOnReconnect
  • refetchOnWindowFocus
  • retry
  • retryOnMount
  • retryDelay
  • select
  • staleTime
  • structuralSharing
  • suspense
  • useErrorBoundary

其中几个高频选项的典型用法:

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 和 '1' 查询同一条记录时,能够命中同一个缓存条目;
  2. 当其他 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。其聚合机制值得展开:

  1. 批量调用(batch):所有同一 tick 内的 useGetManyAggregate 调用会被 batch() 函数收集,通过 setTimeout(..., 0) 合并为一次执行,见源码 useGetManyAggregate.ts;
  2. 按资源与 meta 分组:合并执行时,调用按 ${resource}|${JSON.stringify(meta)} 分组(见 useGetManyAggregate.ts),确保不同资源或不同 meta 的查询不会被错误合并;
  3. id 去重合并:同一组内的 ids 通过 union 去重合并,例如调用 useGetManyAggregate('tags', [1, 2, 3]) 与 useGetManyAggregate('tags', [3, 4]) 会被合并为一次 dataProvider.getMany('tags', [1, 2, 3, 4]);
  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 }

基于以上分析,归纳出以下最佳实践:

  1. 列表内多条引用查询优先用 useGetManyAggregate 或 useReference:它们自动聚合去重,一个页面内多次引用同一资源时只需一次 getMany 请求;
  2. 善用 enabled 控制查询时机:当 id 来自异步上下文(如另一个查询的结果)时,可显式传入 enabled,避免无谓请求;默认行为是 id == null 时不请求;
  3. 利用统一的查询键缓存:[resource, 'getOne', { id: String(id), meta }] 使 getOne 与 getMany 共享缓存,可配合 staleTime、cacheTime 调节新鲜度与缓存保留时长;
  4. 副作用回调使用 onSuccess / onError / onSettled:它们通过 useEvent 保持引用稳定,适合触发通知、刷新等其他 UI 行为;
  5. 需要实时更新时切换到 useGetOneLive:当业务要求记录在服务端变更时前端自动刷新,使用 @react-admin/ra-realtime 提供的实时 Hook;
  6. 为记录声明 TypeScript 泛型:让 data 获得精确类型,减少运行时防御性判断。

延伸阅读

登录后查看全文
react-admin