react-fetch-cache-patterns

实验性 React 数据获取与缓存最佳实践

适用于 React 应用的实现模式：获取并缓存大量 API 请求，同时避免给后端造成过大压力。共分 8 个类别，包含 48 条规则，按执行生命周期的影响排序——前面的类别会逐层影响后续所有内容。模板同时展示基于库（TanStack Query、SWR）和不依赖库（纯 React + AbortController）的实现，无论技术栈有哪些限制，都能使用这些模式。

适用场景

• 编写或审查调用 fetch、useQuery、useSWR 或任何数据获取 Hook 的 React 组件
• 设计列表、信息流或轮播，其中要显示的多个条目都需要获取数据
• 排查“后端请求量过大”或“页面加载缓慢”等问题
• 在客户端获取、路由加载器、服务端组件或 SSR 之间进行选择
• 实现预取、重试、乐观更新或任何故障处理逻辑
• 重构已有的数据获取代码，但其中存在瀑布式请求、没有缓存策略或没有并发限制

按优先级划分的规则类别

#	类别	影响	前缀	规则数
1	请求编排	CRITICAL	orch-	7
2	缓存策略	CRITICAL	cache-	7
3	后端保护	CRITICAL	protect-	7
4	预取与水合	HIGH	prefetch-	6
5	故障韧性	HIGH	resilience-	6
6	信息流与轮播模式	MEDIUM-HIGH	feed-	7
7	变更与失效	MEDIUM	mutate-	4
8	组件模式	MEDIUM	render-	4

快速参考

1. 请求编排（CRITICAL）

• orch-parallelize-independent-fetches — 对互相独立的请求使用 Promise.all；切勿串行 await
• orch-batch-n-plus-one-fanout — 通过 DataLoader 式批处理合并逐行请求
• orch-dedupe-in-flight-requests — 每个键只发起一个进行中的请求，并由多个订阅者共享
• orch-lift-fetch-to-route-loader — 与路由代码块下载并行获取数据
• orch-avoid-effect-chains — 展平依赖图；仅让真正存在依赖关系的任务等待
• orch-server-fetch-when-possible — 如果获取不依赖客户端状态，就将其移到 RSC/服务端
• orch-prefer-bulk-endpoint-for-fanout — 一次批量请求优于 N 次并行请求

2. 缓存策略（CRITICAL）

• cache-deterministic-keys — 规范化缓存键；去除 undefined，排序数组
• cache-normalize-shared-entities — 每个实体只存储一次；视图保存引用
• cache-set-stale-time — 根据数据变化频率而非刷新频率调整 staleTime
• cache-stale-while-revalidate — 立即渲染过期数据；在后台重新验证
• cache-select-subscribed-fields — 订阅数据片段，而非整个对象
• cache-shared-key-factory — 通过统一的类型化数据源管理键，避免读写不一致
• cache-tiered-stale-fresh — 按数据类别设置不同的 staleTime（实时、最新、温热、冷数据、静态）

3. 后端保护（关键）

• protect-concurrency-limit-fanout — 使用 p-limit/信号量限制同时发出的请求数
• protect-collapse-identical-requests — 在 fetch 层合并进行中的重复请求
• protect-debounce-user-driven-fetches — 等待用户暂停操作后再发送搜索/筛选请求
• protect-throttle-scroll-triggered — 使用 IntersectionObserver 触发视口内的数据请求
• protect-jittered-retry-backoff — 添加随机抖动，避免重试时出现惊群效应
• protect-circuit-breaker — 在冷却时间内停止调用持续失败的端点
• protect-rate-limit-aware-client — 遵循 Retry-After 和 X-RateLimit-* 标头

4. 预取与水合（高）

• prefetch-hover-intent-links — 悬停或按下指针时预取，实现即时导航
• prefetch-parallel-loader-queries — 在加载器中并行执行相互独立的查询
• prefetch-hydrate-server-cache — 通过 HydrationBoundary / RSC 传递服务器获取的数据
• prefetch-idle-likely-next — 使用 requestIdleCallback 获取可能需要的下一批数据
• prefetch-viewport-triggered-next-page — 通过 rootMargin 触发下一页预取
• prefetch-budget-and-priority — 按优先级划分预取层级；遵循 Save-Data

5. 故障韧性（高）

• resilience-abort-on-unmount — 传递 AbortSignal，以取消过时的数据请求
• resilience-bounded-timeouts — 通过 AbortSignal.timeout() 为每个端点设置超时
• resilience-scoped-error-boundaries — 每个数据区段设置一个边界，而非每个页面设置一个
• resilience-stale-fallback — 新数据请求失败时渲染过期缓存
• resilience-no-auto-retry-mutations — 使用幂等键，或不要自动重试
• resilience-graceful-degradation — 将内容分为关键、重要和装饰性层级，并采用不同的故障处理方式

6. 信息流与轮播模式（中高）

• feed-virtualize-long-lists — 对超过 50 项的列表使用 TanStack Virtual
• feed-cursor-pagination — 相比偏移量，游标更适合处理插入操作和较大的偏移量
• feed-split-summary-from-detail — 轮播摘要保持轻量；按需加载详情
• feed-multi-carousel-isolation — 为首页信息流中的每个轮播设置错误/Suspense 边界，并提供分层回退
• feed-stable-keys-across-pages — 使用实体 ID 作为键；绝不使用索引
• feed-image-lazy-and-sized — 使用 loading="lazy" + 显式指定尺寸
• feed-bounded-working-set — 使用 maxPages + 实体 LRU 淘汰来限制无界信息流

7. 变更与失效（中）

• mutate-optimistic-updates-with-rollback — 快照、乐观写入，出错时回滚
• mutate-surgical-invalidation — 仅使特定键失效，而非整个树
• mutate-set-data-over-invalidate — 直接将变更响应写入缓存
• mutate-cancel-queries-on-mutate — 乐观写入前取消进行中的查询

8. 组件模式（中）

• render-stable-query-keys — 使用 useMemo 对象键，保持引用稳定
• render-cap-fanout-in-lists — 提升数据获取；通过 DataLoader 批处理；使用虚拟化
• render-suspense-per-section — 每个数据区段设置一个 Suspense 边界
• render-colocate-fetch-with-consumer — 将 useQuery 放在其使用者旁边，而不是根组件中

使用方法

1. 打开 references/_sections.md，了解类别定义和影响说明
2. 阅读各规则文件，查看错误与正确的代码示例
3. 如需可直接使用的脚手架，请参阅 脚手架模板
4. AGENTS.md 导航文档（自动生成）提供了用于浏览的目录

脚手架模板

assets/templates/ 下有六个可直接改编的代码模板：

模板	库依赖	用途
use-resource-query.template.tsx	TanStack Query	标准查询 Hook，包含键工厂、重试、中止和可选的 suspense
use-resource-query-no-deps.template.tsx	无（纯 React + AbortController）	与上述相同的模式，无库依赖：手动实现缓存、去重、带抖动的重试、staleTime/gcTime、并发限制
carousel-data-loader.template.tsx	TanStack Query + react-error-boundary	单个轮播（摘要 + 由视口触发的详情）以及多轮播信息流，并隔离每个轮播的故障
infinite-feed.template.tsx	TanStack Query + TanStack Virtual	使用虚拟化和有界工作集的游标分页无限信息流
prefetch-link.template.tsx	无	悬停/意图预取链接包装器
request-collapser.template.ts	无	进行中的请求去重 + 并发限制工具

无库依赖方案： 如果无法将 TanStack Query / SWR / DataLoader 添加到你的打包产物中（受体积限制、宿主应用冲突或依赖禁用所限），请从 use-resource-query-no-deps.template.tsx 开始——它仅使用 React 和 Web 平台，约 250 行代码即可实现核心缓存/去重/重试/中止模式。其他依赖 TanStack 的模板可以基于此改编；只有 request-collapser 和 prefetch-link 模板开箱即用时没有任何依赖。

参考文件

文件	说明
references/_sections.md	类别定义、排序、影响说明
assets/templates/_template.md	用于编写新规则的模板
metadata.json	版本、参考资料、摘要

相关技能

• react-optimise — 通用 React 渲染性能（本技能专注于数据获取）
• nextjs-bundle-optimizer — Next.js 打包产物/负载优化
• inngest-nextjs-patterns — 服务端工作流模式（补充服务端获取指南）