Refine useInvalidate 详解数据缓存失效的参数体系、Query Key 映射与源码实现【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refinerefine 基于 TanStack Query 管理数据请求与缓存状态useInvalidate是其 core 包中用于主动失效invalidate特定资源或 dataProvider 缓存的 Hook。本篇以 refine 官方 API 参考文档为主体结合仓库中refinedev/core的源码与单元测试讲清它的参数语义、invalidates各取值对应的底层 Query Key 结构以及它与useCreate等 mutation Hook 的协作机制帮助你在需要自定义失效策略的场景下精准控制缓存刷新范围。useInvalidate 的定位refine 使用 TanStack Query 来发起数据请求并维护其状态。所谓失效invalidation即让 TanStack Query 将匹配的查询标记为过期触发活跃查询的重新请求从而拿到最新数据。useInvalidate就是 refine 对外暴露的、面向资源 数据操作语义封装的失效工具它可以失效某个resource资源的缓存也可以配合dataProviderName失效指定 dataProvider 的缓存。需要明确它的定位该 Hook 主要由 refine 内部调用。当 mutation增删改成功后框架会自动调用它来失效相关数据 Hook如 useList、useMany维护的缓存。官方文档明确指出多数场景下你并不需要使用它但 refine 选择将其导出以便在需要定制化失效customized invalidation的场景中使用。基本用法从refinedev/core文档中历史包名为pankod/refine-core导入useInvalidate调用后返回一个invalidate函数接收失效配置对象import { useInvalidate } from refinedev/core; const invalidate useInvalidate(); invalidate({ resource: posts, invalidates: [list], });以上代码表示将posts资源在list操作即列表查询维度的缓存标记为失效。典型失效示例官方文档给出了 5 组典型用法覆盖了最常用的失效粒度组合失效posts资源的list与many状态invalidate({ resource: posts, invalidates: [list, many], });失效id为1的 Posts 详情状态invalidate({ resource: posts, invalidates: [detail], id: 1, });失效名为second-data-provider的 dataProvider 下posts资源的list状态多 dataProvider 场景invalidate({ resource: posts, dataProviderName: second-data-provider, invalidates: [list], });失效名为second-data-provider的 dataProvider 的全部状态invalidate({ dataProviderName: second-data-provider, invalidates: [all], });失效posts资源的全部状态invalidate({ resource: posts, invalidates: [resourceAll], });失效参数详解invalidate接收的配置对象包含以下参数与官方 API 参考表一致参数说明类型默认值invalidates必填要失效的状态集合all、resourceAll、list、many、detail、false数组或false无resource需要失效状态的资源名string无id失效detail状态时使用的idBaseKeyrefine 的 ID 基础类型无dataProviderName要失效其状态的数据提供器名称stringdefaultresourceresource 表示 API 端点中的一个实体例如https://api.fake-rest.refine.dev/posts对应的posts。它用于将失效操作限定在指定资源的缓存范围内。id仅在失效detail状态时使用指需要失效的那条详情记录的主键。dataProviderName当一个 refine 应用中注册了多个dataProvider时通过该参数指定要操作哪一个 provider 的缓存不传时默认操作名为default的 provider。invalidates唯一必填参数决定失效的粒度。支持以下取值all失效所有资源的全部状态resourceAll失效给定resource的全部状态list失效给定resource的list状态对应useList的列表查询缓存detail失效给定resource与id的detail状态对应详情查询缓存many失效给定resource的many状态对应useMany按多 ID 批量查询的缓存。传false或空数组时表示不执行任何失效。源码实现invalidates 如何映射到 Query Key上述取值并非简单的语义标签它们在源码中会精确翻译成 TanStack Query 的 queryKey 前缀匹配规则。useInvalidate的完整实现位于 packages/core/src/hooks/invalidate/index.tsx。核心逻辑分为三步第一步选择 dataProvider 并构造基础 Query Key。源码通过pickDataProvider(resource, dataProviderName, resources)根据资源与dataProviderName解析出实际使用的 providerindex.tsx#L42再借助 refine 的 KeyBuilder 构造基础 keyindex.tsx#L44-L46const dp pickDataProvider(resource, dataProviderName, resources); const queryKey keys() .data(dp) .resource(resource ?? );KeyBuilder 定义在 packages/core/src/definitions/helpers/keys/index.tskeys().data(name?)生成[data, name || default]前缀keys/index.ts#L176-L178.resource()追加资源名.action(one)之后要求再.id()追加主键。这解释了为什么默认dataProviderName是default——Query Key 的第一层命名空间就是 provider 名。第二步按invalidates的每个取值分发失效请求。源码用Promise.all并发执行所有失效操作index.tsx#L48-L88每个取值对应的 queryKey 前缀如下invalidates取值实际调用的queryClient.invalidateQueriesqueryKey 前缀allkeys().data(dp).get()即[data, providerName]resourceAll[data, providerName, resource]list[data, providerName, resource, list]many[data, providerName, resource, many]detail[data, providerName, resource, one, String(id)]注意detail在内部映射到 action 名one且id会被String(id)归一化index.tsx#L75-L83因此数字1与字符串1的 key 一致。switch的default分支对未知取值静默返回不会抛出错误。第三步处理false短路。若invalidates为false函数直接return不发起任何失效index.tsx#L39-L41。从当前仓库的源码还可以看到UseInvalidateProp类型中还定义了invalidationFilters默认{ type: all, refetchType: active }与invalidationOptions默认{ cancelRefetch: false }两个透传给invalidateQueries的选项index.tsx#L14-L21它们让失效行为可以进一步约束哪些状态的查询参与刷新与是否取消进行中的重取这是比 v3 文档时期更细化的能力。测试用例对 Key 结构的验证上述映射关系由单元测试逐一固化。packages/core/src/hooks/invalidate/index.spec.tsx 通过 mockuseQueryClient断言了实际传入的 queryKeyinvalidates: [list]且dataProviderName: rest时断言 queryKey 为[data, rest, posts, list]index.spec.tsx#L70invalidates: [list, detail]、id: 1时同时断言[data, rest, posts, list]与[data, rest, posts, one, 1]index.spec.tsx#L87-L97invalidates: [all]时断言 queryKey 为[data, rest]index.spec.tsx#L117-L121invalidates: false、空数组[]以及非法取值wrong-key三种情况下均断言invalidateQueries未被调用index.spec.tsx#L39-L55、index.spec.tsx#L134-L147。这些断言与源码的 switch 分发逻辑完全对应可以作为参数 → Query Key行为的权威验证依据。与 mutation Hook 的协作为什么增删改后列表会自动刷新useInvalidate的主要消费者是各数据 mutation Hook。以 useCreate 为例其实现位于 packages/core/src/hooks/data/useCreate.tsHook 内部先调用const invalidateStore useInvalidate();useCreate.ts#L126mutation 的onSuccess回调中解构出invalidates默认值为[list, many]useCreate.ts#L174——这就是官方文档所说用useCreate创建一条 Post 后会自动失效posts资源的list与many状态的实现出处随后调用invalidateStore({ resource: identifier, dataProviderName, invalidates })执行失效useCreate.ts#L216-L220。同样地useUpdate、useDelete、useDeleteMany、useUpdateMany、useCreateMany等 Hook位于 packages/core/src/hooks/data/ 目录都在成功回调中复用了useInvalidate。useCreate等 Hook 还向用户暴露了invalidates参数允许在发起 mutation 时覆盖默认失效集合——这是在不直接调用useInvalidate的前提下定制失效行为的第一种方式而直接调用invalidate则是第二种适用于文档、按钮点击、外部事件等非 mutation 场景下的手动缓存刷新例如 RefreshButton 的实现 packages/core/src/hooks/button/refresh-button/index.tsx 同样依赖该 Hook。此外实时数据场景下的useResourceSubscriptionpackages/core/src/hooks/live/useResourceSubscription/index.ts也会根据订阅到的事件调用useInvalidate保证多标签页/多用户协作时的数据一致性。实践建议与注意事项失效粒度从细到粗优先使用list/detail/many等精确粒度只在确认需要同资源所有视图刷新时用resourceAllall会失效该 provider 下所有资源的缓存开销最大应谨慎使用。dataProviderName决定命名空间多 dataProvider 应用中传错或漏传dataProviderName会导致失效目标落到错误的 key 前缀下看似失效了实际刷新不到目标 provider 的缓存。detail必须配合iddetail的 key 以String(id)结尾未传id时 key 段为空字符串将不会命中真实的详情查询源码中id || 的兜底写法可见 index.tsx#L79。invalidates: false是合法的关闭开关框架内部如 mutation Hook依赖它来允许用户完全关闭成功后的自动失效。版本适用说明本篇参数与示例继承自仓库中version-3.xx.xx的 API 参考文档 useInvalidate.md源码级细节如invalidationFilters/invalidationOptions默认值、oneaction 命名以当前仓库packages/core/src下的最新实现为准两者在基础参数语义上保持一致。小结useInvalidate是 refine 数据层缓存一致性的核心枢纽它以invalidates数组为指令集把all、resourceAll、list、many、detail五种失效语义精确编译为 TanStack Query 的 queryKey 前缀匹配[data, provider, resource, action, id]并由Promise.all并发执行。理解这套映射规则后你既能看懂 refine 各 mutation Hook 在成功后自动刷新列表/详情的原因也能在自己的应用中编写精准、低开销的自定义失效逻辑。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Refine useInvalidate 详解：数据缓存失效的参数体系、Query Key 映射与源码实现
Refine useInvalidate 详解数据缓存失效的参数体系、Query Key 映射与源码实现【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refinerefine 基于 TanStack Query 管理数据请求与缓存状态useInvalidate是其 core 包中用于主动失效invalidate特定资源或 dataProvider 缓存的 Hook。本篇以 refine 官方 API 参考文档为主体结合仓库中refinedev/core的源码与单元测试讲清它的参数语义、invalidates各取值对应的底层 Query Key 结构以及它与useCreate等 mutation Hook 的协作机制帮助你在需要自定义失效策略的场景下精准控制缓存刷新范围。useInvalidate 的定位refine 使用 TanStack Query 来发起数据请求并维护其状态。所谓失效invalidation即让 TanStack Query 将匹配的查询标记为过期触发活跃查询的重新请求从而拿到最新数据。useInvalidate就是 refine 对外暴露的、面向资源 数据操作语义封装的失效工具它可以失效某个resource资源的缓存也可以配合dataProviderName失效指定 dataProvider 的缓存。需要明确它的定位该 Hook 主要由 refine 内部调用。当 mutation增删改成功后框架会自动调用它来失效相关数据 Hook如 useList、useMany维护的缓存。官方文档明确指出多数场景下你并不需要使用它但 refine 选择将其导出以便在需要定制化失效customized invalidation的场景中使用。基本用法从refinedev/core文档中历史包名为pankod/refine-core导入useInvalidate调用后返回一个invalidate函数接收失效配置对象import { useInvalidate } from refinedev/core; const invalidate useInvalidate(); invalidate({ resource: posts, invalidates: [list], });以上代码表示将posts资源在list操作即列表查询维度的缓存标记为失效。典型失效示例官方文档给出了 5 组典型用法覆盖了最常用的失效粒度组合失效posts资源的list与many状态invalidate({ resource: posts, invalidates: [list, many], });失效id为1的 Posts 详情状态invalidate({ resource: posts, invalidates: [detail], id: 1, });失效名为second-data-provider的 dataProvider 下posts资源的list状态多 dataProvider 场景invalidate({ resource: posts, dataProviderName: second-data-provider, invalidates: [list], });失效名为second-data-provider的 dataProvider 的全部状态invalidate({ dataProviderName: second-data-provider, invalidates: [all], });失效posts资源的全部状态invalidate({ resource: posts, invalidates: [resourceAll], });失效参数详解invalidate接收的配置对象包含以下参数与官方 API 参考表一致参数说明类型默认值invalidates必填要失效的状态集合all、resourceAll、list、many、detail、false数组或false无resource需要失效状态的资源名string无id失效detail状态时使用的idBaseKeyrefine 的 ID 基础类型无dataProviderName要失效其状态的数据提供器名称stringdefaultresourceresource 表示 API 端点中的一个实体例如https://api.fake-rest.refine.dev/posts对应的posts。它用于将失效操作限定在指定资源的缓存范围内。id仅在失效detail状态时使用指需要失效的那条详情记录的主键。dataProviderName当一个 refine 应用中注册了多个dataProvider时通过该参数指定要操作哪一个 provider 的缓存不传时默认操作名为default的 provider。invalidates唯一必填参数决定失效的粒度。支持以下取值all失效所有资源的全部状态resourceAll失效给定resource的全部状态list失效给定resource的list状态对应useList的列表查询缓存detail失效给定resource与id的detail状态对应详情查询缓存many失效给定resource的many状态对应useMany按多 ID 批量查询的缓存。传false或空数组时表示不执行任何失效。源码实现invalidates 如何映射到 Query Key上述取值并非简单的语义标签它们在源码中会精确翻译成 TanStack Query 的 queryKey 前缀匹配规则。useInvalidate的完整实现位于 packages/core/src/hooks/invalidate/index.tsx。核心逻辑分为三步第一步选择 dataProvider 并构造基础 Query Key。源码通过pickDataProvider(resource, dataProviderName, resources)根据资源与dataProviderName解析出实际使用的 providerindex.tsx#L42再借助 refine 的 KeyBuilder 构造基础 keyindex.tsx#L44-L46const dp pickDataProvider(resource, dataProviderName, resources); const queryKey keys() .data(dp) .resource(resource ?? );KeyBuilder 定义在 packages/core/src/definitions/helpers/keys/index.tskeys().data(name?)生成[data, name || default]前缀keys/index.ts#L176-L178.resource()追加资源名.action(one)之后要求再.id()追加主键。这解释了为什么默认dataProviderName是default——Query Key 的第一层命名空间就是 provider 名。第二步按invalidates的每个取值分发失效请求。源码用Promise.all并发执行所有失效操作index.tsx#L48-L88每个取值对应的 queryKey 前缀如下invalidates取值实际调用的queryClient.invalidateQueriesqueryKey 前缀allkeys().data(dp).get()即[data, providerName]resourceAll[data, providerName, resource]list[data, providerName, resource, list]many[data, providerName, resource, many]detail[data, providerName, resource, one, String(id)]注意detail在内部映射到 action 名one且id会被String(id)归一化index.tsx#L75-L83因此数字1与字符串1的 key 一致。switch的default分支对未知取值静默返回不会抛出错误。第三步处理false短路。若invalidates为false函数直接return不发起任何失效index.tsx#L39-L41。从当前仓库的源码还可以看到UseInvalidateProp类型中还定义了invalidationFilters默认{ type: all, refetchType: active }与invalidationOptions默认{ cancelRefetch: false }两个透传给invalidateQueries的选项index.tsx#L14-L21它们让失效行为可以进一步约束哪些状态的查询参与刷新与是否取消进行中的重取这是比 v3 文档时期更细化的能力。测试用例对 Key 结构的验证上述映射关系由单元测试逐一固化。packages/core/src/hooks/invalidate/index.spec.tsx 通过 mockuseQueryClient断言了实际传入的 queryKeyinvalidates: [list]且dataProviderName: rest时断言 queryKey 为[data, rest, posts, list]index.spec.tsx#L70invalidates: [list, detail]、id: 1时同时断言[data, rest, posts, list]与[data, rest, posts, one, 1]index.spec.tsx#L87-L97invalidates: [all]时断言 queryKey 为[data, rest]index.spec.tsx#L117-L121invalidates: false、空数组[]以及非法取值wrong-key三种情况下均断言invalidateQueries未被调用index.spec.tsx#L39-L55、index.spec.tsx#L134-L147。这些断言与源码的 switch 分发逻辑完全对应可以作为参数 → Query Key行为的权威验证依据。与 mutation Hook 的协作为什么增删改后列表会自动刷新useInvalidate的主要消费者是各数据 mutation Hook。以 useCreate 为例其实现位于 packages/core/src/hooks/data/useCreate.tsHook 内部先调用const invalidateStore useInvalidate();useCreate.ts#L126mutation 的onSuccess回调中解构出invalidates默认值为[list, many]useCreate.ts#L174——这就是官方文档所说用useCreate创建一条 Post 后会自动失效posts资源的list与many状态的实现出处随后调用invalidateStore({ resource: identifier, dataProviderName, invalidates })执行失效useCreate.ts#L216-L220。同样地useUpdate、useDelete、useDeleteMany、useUpdateMany、useCreateMany等 Hook位于 packages/core/src/hooks/data/ 目录都在成功回调中复用了useInvalidate。useCreate等 Hook 还向用户暴露了invalidates参数允许在发起 mutation 时覆盖默认失效集合——这是在不直接调用useInvalidate的前提下定制失效行为的第一种方式而直接调用invalidate则是第二种适用于文档、按钮点击、外部事件等非 mutation 场景下的手动缓存刷新例如 RefreshButton 的实现 packages/core/src/hooks/button/refresh-button/index.tsx 同样依赖该 Hook。此外实时数据场景下的useResourceSubscriptionpackages/core/src/hooks/live/useResourceSubscription/index.ts也会根据订阅到的事件调用useInvalidate保证多标签页/多用户协作时的数据一致性。实践建议与注意事项失效粒度从细到粗优先使用list/detail/many等精确粒度只在确认需要同资源所有视图刷新时用resourceAllall会失效该 provider 下所有资源的缓存开销最大应谨慎使用。dataProviderName决定命名空间多 dataProvider 应用中传错或漏传dataProviderName会导致失效目标落到错误的 key 前缀下看似失效了实际刷新不到目标 provider 的缓存。detail必须配合iddetail的 key 以String(id)结尾未传id时 key 段为空字符串将不会命中真实的详情查询源码中id || 的兜底写法可见 index.tsx#L79。invalidates: false是合法的关闭开关框架内部如 mutation Hook依赖它来允许用户完全关闭成功后的自动失效。版本适用说明本篇参数与示例继承自仓库中version-3.xx.xx的 API 参考文档 useInvalidate.md源码级细节如invalidationFilters/invalidationOptions默认值、oneaction 命名以当前仓库packages/core/src下的最新实现为准两者在基础参数语义上保持一致。小结useInvalidate是 refine 数据层缓存一致性的核心枢纽它以invalidates数组为指令集把all、resourceAll、list、many、detail五种失效语义精确编译为 TanStack Query 的 queryKey 前缀匹配[data, provider, resource, action, id]并由Promise.all并发执行。理解这套映射规则后你既能看懂 refine 各 mutation Hook 在成功后自动刷新列表/详情的原因也能在自己的应用中编写精准、低开销的自定义失效逻辑。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
