Cherry Studio 项目内 React.cache() 服务端单请求去重实战指南从浅比较陷阱到 Next.js 请求记忆化【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio导读本指南以仓库内 Vercel React 最佳实践规则集.agents/skills/vercel-react-best-practices中的server-cache-react规则为骨架系统讲解服务端渲染SSR / RSC场景下如何用React.cache()实现单请求级数据去重。你将掌握cache()的正确用法、Object.is浅比较对缓存命中率的关键影响、内联对象参数导致缓存永远失效的经典陷阱以及 Next.js 中fetch自动记忆化与React.cache()的职责边界。本文结合本仓库实际环境React 19.2.0展开原理分析适合在编写、审查或重构服务端数据获取代码时作为可直接引用的决策依据。一、规则定位为什么单请求去重属于服务端性能高优先级话题server-cache-react规则文件位于仓库的 .agents/skills/vercel-react-best-practices/rules/server-cache-react.md属于该技能包Server-Side Performance服务端性能分类优先级 3、整体影响 HIGH与该分类下的其他规则如 server-cache-lru.md 跨请求 LRU 缓存、server-parallel-fetching.md 并行化请求共同构成服务端优化方案。从影响分级来看见 SKILL.mdCRITICAL消除瀑布流、包体积优化HIGH服务端性能本规则所在分类MEDIUM重渲染优化、渲染性能。React.cache()去重属于 MEDIUM 影响的规则frontmatter 中impact: MEDIUMimpactDescription: deduplicates within request它解决的是同一请求内、同一份数据被组件树多处重复读取的问题——不是跨请求缓存而是消除单次请求内部的冗余 IO。本仓库是一个以 Electron React 19.2.0 为基础的桌面应用见 package.json 中react: ^19.2.0该技能包以可执行规则文件的形式被引入仓库用于指导 Agent 在编写、审查或重构 React/Next.js 代码时自动遵循 Vercel 的工程实践。理解本文规则同样适用于任何采用 React Server Components 或 SSR 架构的项目。二、核心概念React.cache()与单请求去重在 React 服务端渲染中组件树中的多个组件父组件、子组件、布局、页头页脚经常需要读取同一份数据——例如当前登录用户。如果不做任何处理每个组件各自调用一次数据库查询或鉴权函数单次请求就会被放大成多次重复 IO。React.cache()的作用是把任意异步函数包装成同一请求内按参数去重的版本。规则文档给出的典型示例import { cache } from react export const getCurrentUser cache(async () { const session await auth() if (!session?.user?.id) return null return await db.user.findUnique({ where: { id: session.user.id } }) })要点通过import { cache } from react引入注意不是react/cache子路径而是 React 顶层导出把原本直接导出的async函数用cache()包一层导出的是包装后的版本组件树各处import { getCurrentUser }后重复调用规则明确说明在同一请求within a single request内多次调用getCurrentUser()实际只执行一次查询后续调用直接命中缓存返回结果。适用于此模式的最典型场景规则原文强调Authentication and database queries benefit most鉴权检查多个组件都要判断用户是否登录数据库查询用户资料、配置、主题等被多处使用的数据重量级计算、文件系统操作、任何非fetch的异步工作详见本文第五节。三、浅比较陷阱为什么内联对象参数永远缓存不命中React.cache()判定缓存命中的依据是参数的浅比较Object.is语义——即比较参数引用是否相同而不是比较值是否相等。这是本规则最容易踩坑的地方。3.1 反例内联对象 → 每次都是 cache miss规则文档给出的错误示范const getUser cache(async (params: { uid: number }) { return await db.user.findUnique({ where: { id: params.uid } }) }) // Each call creates new object, never hits cache getUser({ uid: 1 }) getUser({ uid: 1 }) // Cache miss, runs query again虽然两次调用传入的对象内容相同都是{ uid: 1 }但它们是两个不同的对象引用。每次函数调用时{ uid: 1 }这个对象字面量都会在内存中新建一个引用Object.is比较发现引用不同判定为 cache miss于是数据库查询被重复执行——去重完全失效。3.2 正例原始值参数 → 值相等即命中const getUser cache(async (uid: number) { return await db.user.findUnique({ where: { id: uid } }) }) // Primitive args use value equality getUser(1) getUser(1) // Cache hit, returns cached result原始类型number、string、boolean在Object.is比较下按值相等判定getUser(1)与getUser(1)被视为同一缓存键第二次调用直接返回缓存结果不再触发查询。3.3 如果必须传对象复用同一个引用规则文档同时给出了必须传对象时的补救方案const params { uid: 1 } getUser(params) // Query runs getUser(params) // Cache hit (same reference)把对象提升为外部常量多次调用传同一个引用Object.is比较通过缓存命中。这条规则可以总结为一句工程口诀给React.cache()包装的函数传参时优先传原始值必须传对象时保证引用稳定模块级常量、组件外定义的对象。四、Next.js 中的职责划分fetch自动记忆化 vsReact.cache()规则文档特别说明了 Next.js 场景下的一个容易混淆点在 Next.js 中fetchAPI 被自动扩展了请求记忆化request memoization。同一 URL 与同一 options 的请求在单个请求内会被自动去重因此fetch调用不需要也不建议再包一层React.cache()。也就是说对于直接调fetch拉接口的场景Next.js 框架层已经内置了与React.cache()等价甚至更强的去重能力再手动包一层是重复劳动。但React.cache()仍然是其他非fetch异步任务的必需品。规则文档列出的适用清单数据库查询Prisma、Drizzle 等 ORM 的查询调用重量级计算鉴权检查文件系统操作任何非fetch的异步工作。例如auth()鉴权会话读取、db.user.findUnique()数据库查询这类函数不会享受 Next.js 的 fetch 记忆化必须由开发者用React.cache()显式去重。规则建议用React.cache()在组件树范围内对这些操作统一去重让整棵组件树共享一份结果。五、边界与配套方案单请求去重之外的缓存层次React.cache()的作用域严格限定在单次请求内服务端渲染完成即失效。要构建完整的缓存体系需要与技能包内其他规则配合5.1 跨请求缓存交给 LRUserver-cache-lru当用户连续操作点按钮 A、再点按钮 B需要在多个顺序请求之间共享同一份数据时单请求去重无法覆盖应使用 LRU 缓存。规则 server-cache-lru.md 给出实现import { LRUCache } from lru-cache const cache new LRUCachestring, any({ max: 1000, ttl: 5 * 60 * 1000 // 5 minutes }) export async function getUser(id: string) { const cached cache.get(id) if (cached) return cached const user await db.user.findUnique({ where: { id } }) cache.set(id, user) return user }该规则同时提醒部署形态差异在支持实例复用的计算平台上LRU 缓存可跨并发请求共享、无需外部存储而在传统 serverless 隔离执行环境下应考虑 Redis 等外部存储做跨进程缓存。5.2 客户端去重交给 SWRclient-swr-dedup把视角切换到浏览器端client-swr-dedup.md 建议用useSWR实现跨组件实例的自动去重、缓存与重新验证避免多个组件各自useEffect里发fetch造成重复请求。5.3 三者边界速查缓存层次工具作用域典型场景单请求内React.cache()一次 SSR / RSC 请求鉴权、DB 查询、重计算被组件树多处读取跨请求LRU 缓存同一运行实例内顺序请求共享热点数据秒级 TTL客户端SWR浏览器端跨组件多个组件实例共享同一接口数据三者互补而不重叠React.cache()管这一次渲染内部别重复干活LRU 管连续几次请求之间别重复干活SWR 管浏览器里别重复发请求。六、落地检查清单在编写或审查代码时对照以下清单判断是否需要、以及如何正确使用React.cache()是否命中场景该异步操作是否会在一次请求内被组件树多处调用鉴权、用户信息、配置、公共查询是 → 值得包cache()。参数形态传给cache()包装函数的参数是否是原始值如果被迫传对象是否复用了稳定引用模块级常量警惕内联对象getUser({ uid: 1 })这种写法等于放弃去重必须改写为getUser(1)或复用同一引用。不要重复包裹 fetchNext.js 中对fetch已有自动记忆化直接使用即可React.cache()留给 DB 查询、鉴权、文件 IO、重计算。区分缓存作用域需要跨请求共享数据时升级到 LRUserver-cache-lru.md而非依赖React.cache()浏览器端去重使用 SWRclient-swr-dedup.md。注意安全边界鉴权类结果缓存于单请求生命周期内是安全的每次请求重新鉴权切勿把鉴权结果错误地放进跨请求缓存参见同分类 server-auth-actions.md 对鉴权时机的强调。七、小结React.cache()是服务端渲染场景下消灭同一请求内重复 IO的最轻量手段成本仅是一次函数包装收益是整棵组件树共享一次查询/鉴权结果。本规则的核心知识可以压缩为三点用cache()包住非 fetch 的异步操作用原始值或稳定引用做参数把跨请求需求交给 LRU、把客户端需求交给 SWR。在 Cherry Studio 仓库的工程环境下该规则以server-cache-react文件形式沉淀于 .agents/skills/vercel-react-best-practices/rules/可作为代码编写、审查与自动重构时可直接引用的权威依据。【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考