react-admin useGetOne 数据获取 Hook 完全指南:单条记录查询、聚合优化与缓存原理

原创2026-09-21 15:04:281,741 阅读
文章标签:前端UI组件

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):

  • 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

其中 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-query useQuery 的完整选项列表,其中 enabled 默认与 id != null 联动,空 id 不发起请求;
  • 页面多处查询同一资源时,改用 useGetManyAggregate(同 tick 内聚合成一次 getMany 并写回 getOne 缓存)或 useReference(面向引用记录的语义化封装)以减少数据提供者调用次数;
  • 通过返回的 refetch 可随时手动刷新记录;配合泛型可获得完整的 TypeScript 类型推导。

若想进一步了解数据提供者如何实现 getOne,可参考 DataProviderWriting、DataProviderList 与 DataFetchingGuide;完整的 Hook 列表见 useGetOne.md 同目录下的其他文档,以及 ra-core 的 dataProvider 模块。

登录后查看全文
react-admin