react-admin 的 useDataProvider 深入解析在任意组件中直接调用 Data Provider 的完整指南【免费下载链接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design项目地址: https://gitcode.com/gh_mirrors/re/react-adminuseDataProvider是 react-admin 数据层最底层的入口之一它以 Hook 的形式把仓库中通过 Context 存储的dataProvider对象暴露给任意组件让你绕过useGetOne、useUpdate等高层数据 Hook直接调用数据提供器的全部方法。本文以官方文档 docs/useDataProvider.md 为主线结合 ra-core 的源码实现与测试用例带你掌握其语法、底层 Proxy 包装器原理、自定义方法调用范式以及 TypeScript 类型安全写法。认识 useDataProvider定位与语法react-admin 会把dataProvider对象存进一个 React Context即DataProviderContext定义于 DataProviderContext.ts因此它在整个应用代码中都可用。useDataProviderHook 负责把这个对象取出来交给开发者直接调用const dataProvider useDataProvider();Hook 不接收任何参数返回 Data Provider。之后就可以直接调用其方法dataProvider.getOne(users, { id: 123 }) .then(({ data }) { // 处理返回的单条记录 });由于dataProvider的所有方法都是异步的均返回 Promisereact-admin 官方文档给出了两条实践准则查询query类调用放在 React 的useEffect中执行变更mutation类调用放在事件处理器如按钮的onClick中执行。这里有一个非常关键且容易忽略的事实——从useDataProvider拿到的dataProvider并不是你传入的那个原始对象而是一个包装器wrapper。官方文档明确提示如果dataProvider返回了错误且authProvider.checkError()认定该错误是认证错误这个包装器会自动把用户登出。下文会结合源码详细拆解这层包装做了什么。源码视角Context 取值与 Proxy 包装器useDataProvider的实现位于 useDataProvider.ts核心逻辑分为两步。第一步从 Context 取值并提供兜底。const dataProvider (useContext(DataProviderContext) || defaultDataProvider) as unknown as TDataProvider;如果当前组件不在AdminContext/CoreAdminContext内部Context 值为null此时会回退到 defaultDataProvider.ts 中定义的默认实现——一个所有方法都返回空结果的桩对象如getList返回{ data: [], total: 0 }、getOne返回{ data: null }。从源码注释可以看出这主要是为了避免在测试中强制要求包裹 Context。第二步用 Proxy 构造一层包装器。真正的返回对象是new Proxy(dataProvider, { get: ... })创建的代理。每次访问dataProvider.xxx时get拦截器都会返回一个统一的调用函数这个函数依次完成了四件关键工作方法存在性校验若访问的方法在 dataProvider 上不存在会抛出Unknown dataProvider function: xxx错误开发模式响应格式校验当NODE_ENV development且方法属于标准 fetch 动作见 dataFetchActions.ts 中的reactAdminFetchActions时会对返回结果调用validateResponseFormat(response, type)做格式校验预取数据填充缓存若响应携带meta.prefetched字段则调用populateQueryCache把预取数据写入 React Query 缓存从而让相关useGetMany等 Hook 免于再次请求错误拦截与登出Promise 失败时在非生产环境打印错误AbortError除外随后调用useLogoutIfAccessDenied返回的登出函数。其中第 4 步正是文档中 wrapper 的落脚点useLogoutIfAccessDenied实现见 useLogoutIfAccessDenied.ts会把错误交给authProvider.checkError()判定若判定为认证失败如 401/403就触发登出并提示用户。登出后的返回值空数据而非崩溃一个值得注意的细节是当因认证失败触发登出后包装器不会把错误继续抛给调用方而是根据方法类型返回空数据return logoutIfAccessDenied(error).then(loggedOut { if (loggedOut) return { data: arrayReturnTypes.includes(type) ? [] : {}, }; throw error; });其中arrayReturnTypes是[getList, getMany, getManyReference]。也就是说列表类查询会得到{ data: [] }单记录类查询会得到{ data: {} }。这一行为在测试 useDataProvider.spec.tsx 的 should return array or object when 401 用例中得到了验证四个方法getList、getMany、getOne、getManyReference在checkError拒绝时分别返回了对应的空结果。同步抛错被规范化如果dataProvider的某个方法不是返回 rejected Promise而是同步 throw包装器会捕获并改抛一个更明确的错误The dataProvider threw an error. It should return a rejected Promise instead.对应的测试用例同样覆盖了这一行为见 spec 文件中 should display a meaningful error when the dataProvider throws a sync error。开发环境的响应格式校验validateResponseFormat实现见 validateResponseFormat.ts只在开发模式生效用于尽早暴露 dataProvider 的错误实现。它会依次检查响应是否为空是否包含data键数组类方法getList、getMany、getManyReference、updateMany、deleteMany的data是否为数组标识记录类方法getList、getMany、getManyReference等返回的数组项是否带id单记录类方法getOne、create、update返回的data是否带idgetList、getManyReference是否带total或pageInfo。校验失败会抛出ra.notification.data_provider_error。测试 should call getList and show error in development environment 验证了在开发环境下格式错误的响应会触发错误提示而在 test / production 环境下则不提示。基础用法在 useEffect 中查询用户资料文档给出了一个最经典的实践——用useDataProvider直接查询当前用户资料并自行管理loading/error/ 数据三种状态import { useState, useEffect } from react; import { useDataProvider } from react-admin; import { Loading, Error } from ./MyComponents; const UserProfile ({ userId }) { const dataProvider useDataProvider(); const [user, setUser] useState(); const [loading, setLoading] useState(true); const [error, setError] useState(); useEffect(() { dataProvider.getOne(users, { id: userId }) .then(({ data }) { setUser(data); setLoading(false); }) .catch(error { setError(error); setLoading(false); }) }, []); if (loading) return Loading /; if (error) return Error /; if (!user) return null; return ( ul liName: {user.name}/li liEmail: {user.email}/li /ul ) };需要注意两点useEffect的依赖数组为空可能导致在userId变化时不重新请求生产代码建议把userId纳入依赖或结合闭包捕获最新值这段代码完全绕过了 React Query 的缓存与去重机制因此仅适用于数据获取频率低、且需要完全自己掌控状态的场景。顺带一提useDataProvider也可以用在AdminContext之外由Admin组件管理的更上层场景——Admin.tsx 的文档示例展示了如何在自定义的Resources组件中用它调用dataProvider.introspect()来动态发现资源并生成界面。何时不该用 useDataProvider标准方法优先文档反复强调一个工程判断调用getOne()、update()这类标准方法时应尽量少用useDataProvider。因为 react-admin 为每个标准方法都提供了对应的数据 Hook例如查询类query hooksuseGetOne、useGetList、useGetMany等变更类mutation hooksuseUpdate、useCreate、useDelete等。关于 query hooks 与 mutation hooks 的完整清单可参阅 Actions.md 中的 Query Hooks 与 Mutation Hooks 两节。这些高层 Hook 自动集成了 React Query 的缓存、自动刷新、乐观更新、loading/error 状态管理等功能比手动useEffect then/catch的写法更简洁、更不易出错。核心价值调用 dataProvider 的自定义方法useDataProvider真正的用武之地是调用你添加到 dataProvider 上的自定义方法。标准 dataProvider 类型在 types.ts 中声明了 9 个方法getList、getOne、getMany、getManyReference、create、update、updateMany、delete、deleteMany但其末尾的索引签名[key: string]: any与可选字段supportAbortSignal?: boolean允许你任意扩展。例如假设你的 dataProvider 暴露了一个banUser()方法const dataProvider { getList: /* ... */, getOne: /* ... */, getMany: /* ... */, getManyReference: /* ... */, create: /* ... */, update: /* ... */, updateMany: /* ... */, delete: /* ... */, deleteMany: /* ... */, banUser: (userId) { return fetch(/api/user/${userId}/ban, { method: POST }) .then(response response.json()); }, }在按钮点击事件中调用它时文档推荐与 React Query 的useMutation组合使用从而免费获得isPending等变更状态管理import { useDataProvider, Button } from react-admin; import { useMutation } from tanstack/react-query; const BanUserButton ({ userId }) { const dataProvider useDataProvider(); const { mutate, isPending } useMutation({ mutationFn: () dataProvider.banUser(userId) }); return Button labelBan onClick{() mutate()} disabled{isPending} /; };自定义方法同样享受 Proxy 包装器的统一待遇错误会被交给authProvider.checkError()判定、登出逻辑照常生效。从测试 useDataProvider.spec.tsx 的 custom verbs 系列用例可以看到自定义方法的参数会原样透传——既可以按标准的(resource, params)签名调用也可以无参调用或传入任意自定义参数。TypeScript 实践让自定义方法与记录类型获得类型安全为自定义方法扩展类型useDataProvider接受一个泛型参数来声明 dataProvider 的类型。当你在 dataProvider 上增加了自定义方法时应先用接口继承标准DataProvider再通过泛型传给 Hook// src/dataProvider.ts import { DataProvider } from react-admin; export interface DataProviderWithCustomMethods extends DataProvider { archive: (resource: string, params: { id: number; }) Promiseany } export const dataProvider: DataProviderWithCustomMethods { // ...标准 dataProvider 方法 archive: (resource, params) { // 调用 archive 端点并返回一个 Promise } }在组件中通过泛型调用编辑器与 TypeScript 就能识别出自定义方法// src/ArchiveButton.tsx import { Button, useDataProvider } from react-admin; import ArchiveIcon from mui/icons-material/Archive; import { DataProviderWithCustomMethods } from ./dataProvider; export const ArchiveButton () { const dataProvider useDataProviderDataProviderWithCustomMethods(); const record useRecord(); return ( Button labelArchive onClick{() { // TypeScript 能识别 archive 方法 dataProvider.archive(resource, { id: record.id }) }} ArchiveIcon / /Button ); };标准方法的记录类型泛型此外标准 dataProvider 方法本身也接受记录类型泛型。从 types.ts 可以看到每个方法都声明为泛型函数如getOne: RecordType extends RaRecord any(...) PromiseGetOneResultRecordType因此你可以这样获得精确的返回类型dataProvider.getOneProduct(users, { id: 123 }) .then(({ data }) { // TypeScript 知道 data 的类型是 Product // ... })小结关注点结论适用场景调用 dataProvider 的自定义方法、需要绕过高层数据 Hook 的底层直连不适用场景标准方法调用应优先使用useGetOne、useUpdate等 query/mutation hooks返回值一个 Proxy 包装器非原始 dataProvider附加能力开发模式响应格式校验、meta.prefetched缓存预填、认证失败自动登出错误行为未知方法抛错同步 throw 被规范为 Promise 错误登出时按方法类型返回空数据类型安全useDataProviderT()自定义类型 getOneProduct()记录泛型如果你需要更深入地研究这层包装的每一处细节可以从仓库中的以下文件入手useDataProvider.ts实现、useDataProvider.spec.tsx行为测试、validateResponseFormat.ts格式校验、types.tsDataProvider 类型定义。【免费下载链接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design项目地址: https://gitcode.com/gh_mirrors/re/react-admin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考