Mastra React 前端数据请求去重指南基于 TanStack Query 的自动去重最佳实践【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读在 Mastra 的 React 前端工程中如 playground-ui 这类基于mastra/react TanStack Query 构建的管理界面同一份数据常常会被多个组件实例同时消费如果每个实例各自发一次请求就会产生重复的网络开销、额外的 loading 闪烁和状态不一致。本篇指南基于仓库内 React 最佳实践规则 client-request-dedupe.md讲解如何利用 TanStack Query 实现请求的自动去重deduplication、缓存与再验证并深入 Mastra 仓库源码packages/playground-ui 下的 hooks 与测试验证这些模式的实际落地方式。读完本文你将掌握queryKey 去重原理、不可变数据与 mutation 的正确用法以及依赖参数下保持 hook 类型严格性的skipToken收窄策略。一、问题背景没有去重时每个实例各发一次请求Mastra React 前端会大量出现同一路由、同一数据源被多个组件同时渲染的场景——例如日志列表、Memory 线程消息、Trace 详情等可能同时存在于页面主体、侧边栏预览和详情面板中。若沿用useState useEffect的传统写法每个组件实例都会独立发起fetch造成 N 份组件实例 N 次网络请求function UserList() { const [users, setUsers] useState([]); useEffect(() { fetch(/api/users) .then(r r.json()) .then(setUsers); }, []); }这是 client-request-dedupe.md 明确标注的Incorrect反模式没有去重、没有缓存、没有跨实例共享且useEffect的二次渲染还会带来额外的状态同步问题。它属于仓库规则体系中Client-Side Data Fetching客户端数据请求影响级别 MEDIUM-HIGH类别在 SKILL.md 的优先级排序中位列第三梯队仅次于消除瀑布流和包体积优化。二、核心解法queryKey 驱动的自动去重TanStack Query 的自动去重建立在queryKey 即缓存地址这一核心机制上多个组件实例只要使用相同的queryKey就会被归并到同一个查询观察者QueryObserver共享同一次queryFn发出的请求与同一份缓存数据。import { useQuery } from tanstack/react-query; function UserList() { const { data: users } useQuery({ queryKey: [users], queryFn: () fetch(/api/users).then(r r.json()), }); }要点拆解queryKey的等价性决定去重与否[users]与[users]是同一个查询一旦 key 序列化结果不同如[users, page]与[users, page1]则视为不同查询各自独立请求——这正是分页场景下多页请求可以并存的原因。queryFn只执行一次同一时间窗内多个订阅同一 key 的组件实例只有第一个会真正触发请求其余实例直接消费进行中的 Promise请求完成后所有实例同步收到数据。后续重挂载零成本组件卸载再挂载时只要缓存未过期且未超过gcTime直接命中缓存不发新请求。Mastra 仓库中use-logs.ts 是这一机制的进阶应用——它使用useInfiniteQuery管理日志分页queryKey 为[logs, filters]翻页参数通过pageParam驱动const query useInfiniteQueryListLogsResponse, Error, ReturnTypetypeof selectLogs, readonly unknown[], number({ queryKey: [logs, filters], queryFn: ({ pageParam }) client.listLogsVNext({ pagination: { page: pageParam, perPage: LOGS_PER_PAGE }, filters, orderBy: { field: timestamp, direction: DESC }, }), initialPageParam: 0, getNextPageParam, select: selectLogs, retry: false, refetchInterval: getLogsRefetchInterval, });注意queryFn直接调用useMastraClient()返回的 SDK client来自mastra/react而不是裸fetch——这是 Mastra 前端的标准姿势请求路径交给官方 SDK去重与缓存交给 TanStack Query。同时该文件展示了两个值得借鉴的细节refetchInterval的动态开关当观测性服务不可用isObservabilityUnavailableError或操作不支持时返回false停止轮询避免对故障端点持续空转见 getLogsRefetchInterval。select对跨页数据的去重基于 offset 的分页在两次fetchNextPage之间若有新日志插入会在页边界产生重复行selectLogs 用Set按logId去重并在缺失logId时回退到完整序列化记录防止同键误合并。三、不可变数据用staleTime: Infinity杜绝重复请求对于部署后几乎不变的配置类数据如/api/config、UI 开关、静态字典每次重挂载都重新请求纯属浪费。规则给出的做法是将数据标记为永不失效import { useQuery } from tanstack/react-query; function StaticContent() { const { data } useQuery({ queryKey: [config], queryFn: () fetch(/api/config).then(r r.json()), staleTime: Infinity, }); }原理TanStack Query 用staleTime控制数据新鲜度新鲜数据在窗口期内不会被后台重新拉取staleTime: Infinity意味着数据一旦取得便永不视为过期后续挂载与聚焦一律走缓存。它不影响手动refetch()或invalidateQueries的强制刷新因此适合数据稳定但允许被显式失效的场景。Mastra 仓库中对时效性做精细化控制的例子见 use-trace-insight.ts它为 LLM Trace 洞察结果设置了staleTime: 30_00030 秒内不重复请求并刻意在 queryKey 中省略 entity 维度——因为源 traceId 全局唯一且端点不按实体区分key 故意省略 entityType/entityId这正是queryKey 只包含真正参与请求标识的字段的实践注脚。四、写操作useMutation而不是手写状态机凡是改变服务端状态的请求更新、删除、创建都不应放进useQuery的queryFn——查询是幂等可重复的突变不是。规则统一使用useMutationimport { useMutation } from tanstack/react-query; function UpdateButton() { const { mutate } useMutation({ mutationFn: updateUser, }); return button onClick{() mutate()}Update/button; }useMutation自带 pending/error/success 生命周期状态与失败回滚钩子配合queryClient.invalidateQueries可以精准地让受影响的查询失效并自动重取避免手写请求中/成功/失败三态 flag 带来的状态泄漏。五、依赖参数保持 hook 严格在调用方收窄带参数的数据请求如按projectId拉取项目详情是去重与类型安全最容易失守的地方。规则的立场非常明确分为两条路径路径 A调用方收窄首选——hook 保持严格类型A param is either the value orundefined— never add| nullas a third absence type, and never pass a fake value likeid ?? to satisfy the signature.参数只有值或undefined两种形态绝不引入| null作为第三种缺失类型也绝不用id ?? 之类的假值去糊弄类型签名。首选方案是hook 保持严格签名id: string由读取原始参数的组件先做守卫参数存在时才渲染调用该 hook 的子组件参数缺失时整个查询就不应该存在function ProjectPage() { const [searchParams] useSearchParams(); const projectId searchParams.get(projectId) ?? undefined; if (!projectId) return Navigate to/projects /; return ProjectDetail projectId{projectId} /; } function ProjectDetail({ projectId }: { projectId: string }) { // The hook input stays string; loading/error are owned here — // see structure-early-return-render-branches. const { data, isLoading, error } useProject(projectId); // ... } function useProject(projectId: string) { return useQuery({ queryKey: [project, projectId], queryFn: () fetchProject(projectId), }); }这种父组件守卫 条件渲染子组件的结构有多个收益hook 输入类型永远是string调用方想传假值都过不了编译loading/error 归属清晰由子组件独立负责渲染分支与仓库规则 structure-early-return-render-branches.md 呼应同时天然满足本规则开头的去重要求——[project, projectId]相同的 queryKey 在多处共享同一请求。路径 B组件必须提前挂载时——用skipToken守卫查询函数当组件必须在参数出现前就保持挂载例如查询被另一个 flag 门控、参数由异步流程注入才允许把 hook 入参放宽为id?: string此时用skipToken守卫 queryFn而不是非空断言import { skipToken, useQuery } from tanstack/react-query; function useProject(projectId?: string, enabled true) { return useQuery({ queryKey: [project, projectId], queryFn: projectId ? () fetchProject(projectId) : skipToken, enabled, }); }为什么用skipToken而非enabled: false 非空断言skipToken是类型安全的查询禁用方式——当它被传给queryFn时TanStack Query 的 TS 类型会推导出data为undefined编译器会强制你处理数据尚不存在的分支而enabled: false只控制执行类型上仍认为data可用逼出data!之类的断言正是仓库规则体系坚决反对的写法参见 types-no-type-assertions.md。规则还特别提醒一个边界skipToken在参数缺失期间会禁用手动refetch()。如果调用方需要在缺失窗口内主动刷新就应当回到路径 A 在调用方收窄而不是为了迁就refetch而弱化 hook。总原则一句话严格 hook 保持严格——如果 hook 签名是id: string调用方就必须传真实 id。仓库里的 skipToken 实战上述模式在 Mastra 的 playground-ui 中有多处真实落地均严格遵循可选参数 skipToken守卫use-memory-thread-messages.tsMemory 线程消息分页查询export function useMemoryThreadMessages(threadId: string | undefined, opts?: { page?: number; perPage?: number }) { const client useMastraClient(); const page opts?.page ?? 0; const perPage opts?.perPage ?? 100; return useQuery({ queryKey: memoryThreadMessagesQueryKey(threadId, page), queryFn: threadId ? () client.getMemoryThread({ threadId }).listMessages({ page, perPage }) : skipToken, }); }这里的threadId可能来自尚未选中的列表项可为undefined因此 hook 接受可选参数而queryFn用三元表达式在参数缺失时退化为skipToken。queryKey 也由独立的memoryThreadMessagesQueryKey工厂函数生成[memory, thread, threadId, messages, page ?? 0] as const保证 key 结构统一、可被其他代码精确引用以执行invalidateQueries。同类的还有use-memory-status.tsMemory 状态查询参数不存在时同样走skipTokenuse-observational-memory.ts观测性 Memory 查询条件成立才执行queryFnuse-trace-insight.tstraceId undefined ? skipToken : () fetchTraceInsight(request, traceId)。这些 hooks 的测试也验证了去重 依赖参数的组合行为——memory-hooks.test.tsx、use-logs.msw.test.tsx、use-trace-spans.msw.test.tsx 等测试遵循仓库的 BDD 测试策略驱动真实的mastra/client-js React Query 栈只 mock 网络层绝不vi.mock自有 hooks/SDK见 testing-bdd-no-mocks.md。六、落地检查清单对照 client-request-dedupe.md 与仓库实践评审或编写 Mastra React 代码时依次确认数据是否通过useQuery消费同源数据绝不写useState useEffect fetch的组合queryKey 保持稳定、最小、可序列化。queryKey 是否准确描述请求标识参数全部进入 key如[project, projectId]常量性数据不放 key仅当 key 相同才能共享请求key 变更才触发新请求。不可变数据是否设置了staleTime: Infinity或按数据特征给定精确的staleTime如仓库中的30_000避免无意义的后台重取。写操作是否走useMutation并通过invalidateQueries联动相关查询刷新。依赖参数 hook 是否严格首选调用方守卫 条件渲染hook 签名保持id: string确需可选参数时用skipToken守卫queryFn绝不使用| null第三态、假值填充或非空断言。是否考虑了refetch与禁用态的交互skipToken禁用期间无手动refetch有此需求就在调用方收窄而非弱化 hook。这套模式让 Mastra 的 React 前端在多组件共享、列表分页、记忆回放、Trace 洞察等高频数据场景中把网络请求数压缩到理论最小值同时通过类型系统把数据缺失变成编译器可见的事实——去重与类型安全最终是一件事。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mastra React 前端数据请求去重指南：基于 TanStack Query 的自动去重最佳实践
Mastra React 前端数据请求去重指南基于 TanStack Query 的自动去重最佳实践【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读在 Mastra 的 React 前端工程中如 playground-ui 这类基于mastra/react TanStack Query 构建的管理界面同一份数据常常会被多个组件实例同时消费如果每个实例各自发一次请求就会产生重复的网络开销、额外的 loading 闪烁和状态不一致。本篇指南基于仓库内 React 最佳实践规则 client-request-dedupe.md讲解如何利用 TanStack Query 实现请求的自动去重deduplication、缓存与再验证并深入 Mastra 仓库源码packages/playground-ui 下的 hooks 与测试验证这些模式的实际落地方式。读完本文你将掌握queryKey 去重原理、不可变数据与 mutation 的正确用法以及依赖参数下保持 hook 类型严格性的skipToken收窄策略。一、问题背景没有去重时每个实例各发一次请求Mastra React 前端会大量出现同一路由、同一数据源被多个组件同时渲染的场景——例如日志列表、Memory 线程消息、Trace 详情等可能同时存在于页面主体、侧边栏预览和详情面板中。若沿用useState useEffect的传统写法每个组件实例都会独立发起fetch造成 N 份组件实例 N 次网络请求function UserList() { const [users, setUsers] useState([]); useEffect(() { fetch(/api/users) .then(r r.json()) .then(setUsers); }, []); }这是 client-request-dedupe.md 明确标注的Incorrect反模式没有去重、没有缓存、没有跨实例共享且useEffect的二次渲染还会带来额外的状态同步问题。它属于仓库规则体系中Client-Side Data Fetching客户端数据请求影响级别 MEDIUM-HIGH类别在 SKILL.md 的优先级排序中位列第三梯队仅次于消除瀑布流和包体积优化。二、核心解法queryKey 驱动的自动去重TanStack Query 的自动去重建立在queryKey 即缓存地址这一核心机制上多个组件实例只要使用相同的queryKey就会被归并到同一个查询观察者QueryObserver共享同一次queryFn发出的请求与同一份缓存数据。import { useQuery } from tanstack/react-query; function UserList() { const { data: users } useQuery({ queryKey: [users], queryFn: () fetch(/api/users).then(r r.json()), }); }要点拆解queryKey的等价性决定去重与否[users]与[users]是同一个查询一旦 key 序列化结果不同如[users, page]与[users, page1]则视为不同查询各自独立请求——这正是分页场景下多页请求可以并存的原因。queryFn只执行一次同一时间窗内多个订阅同一 key 的组件实例只有第一个会真正触发请求其余实例直接消费进行中的 Promise请求完成后所有实例同步收到数据。后续重挂载零成本组件卸载再挂载时只要缓存未过期且未超过gcTime直接命中缓存不发新请求。Mastra 仓库中use-logs.ts 是这一机制的进阶应用——它使用useInfiniteQuery管理日志分页queryKey 为[logs, filters]翻页参数通过pageParam驱动const query useInfiniteQueryListLogsResponse, Error, ReturnTypetypeof selectLogs, readonly unknown[], number({ queryKey: [logs, filters], queryFn: ({ pageParam }) client.listLogsVNext({ pagination: { page: pageParam, perPage: LOGS_PER_PAGE }, filters, orderBy: { field: timestamp, direction: DESC }, }), initialPageParam: 0, getNextPageParam, select: selectLogs, retry: false, refetchInterval: getLogsRefetchInterval, });注意queryFn直接调用useMastraClient()返回的 SDK client来自mastra/react而不是裸fetch——这是 Mastra 前端的标准姿势请求路径交给官方 SDK去重与缓存交给 TanStack Query。同时该文件展示了两个值得借鉴的细节refetchInterval的动态开关当观测性服务不可用isObservabilityUnavailableError或操作不支持时返回false停止轮询避免对故障端点持续空转见 getLogsRefetchInterval。select对跨页数据的去重基于 offset 的分页在两次fetchNextPage之间若有新日志插入会在页边界产生重复行selectLogs 用Set按logId去重并在缺失logId时回退到完整序列化记录防止同键误合并。三、不可变数据用staleTime: Infinity杜绝重复请求对于部署后几乎不变的配置类数据如/api/config、UI 开关、静态字典每次重挂载都重新请求纯属浪费。规则给出的做法是将数据标记为永不失效import { useQuery } from tanstack/react-query; function StaticContent() { const { data } useQuery({ queryKey: [config], queryFn: () fetch(/api/config).then(r r.json()), staleTime: Infinity, }); }原理TanStack Query 用staleTime控制数据新鲜度新鲜数据在窗口期内不会被后台重新拉取staleTime: Infinity意味着数据一旦取得便永不视为过期后续挂载与聚焦一律走缓存。它不影响手动refetch()或invalidateQueries的强制刷新因此适合数据稳定但允许被显式失效的场景。Mastra 仓库中对时效性做精细化控制的例子见 use-trace-insight.ts它为 LLM Trace 洞察结果设置了staleTime: 30_00030 秒内不重复请求并刻意在 queryKey 中省略 entity 维度——因为源 traceId 全局唯一且端点不按实体区分key 故意省略 entityType/entityId这正是queryKey 只包含真正参与请求标识的字段的实践注脚。四、写操作useMutation而不是手写状态机凡是改变服务端状态的请求更新、删除、创建都不应放进useQuery的queryFn——查询是幂等可重复的突变不是。规则统一使用useMutationimport { useMutation } from tanstack/react-query; function UpdateButton() { const { mutate } useMutation({ mutationFn: updateUser, }); return button onClick{() mutate()}Update/button; }useMutation自带 pending/error/success 生命周期状态与失败回滚钩子配合queryClient.invalidateQueries可以精准地让受影响的查询失效并自动重取避免手写请求中/成功/失败三态 flag 带来的状态泄漏。五、依赖参数保持 hook 严格在调用方收窄带参数的数据请求如按projectId拉取项目详情是去重与类型安全最容易失守的地方。规则的立场非常明确分为两条路径路径 A调用方收窄首选——hook 保持严格类型A param is either the value orundefined— never add| nullas a third absence type, and never pass a fake value likeid ?? to satisfy the signature.参数只有值或undefined两种形态绝不引入| null作为第三种缺失类型也绝不用id ?? 之类的假值去糊弄类型签名。首选方案是hook 保持严格签名id: string由读取原始参数的组件先做守卫参数存在时才渲染调用该 hook 的子组件参数缺失时整个查询就不应该存在function ProjectPage() { const [searchParams] useSearchParams(); const projectId searchParams.get(projectId) ?? undefined; if (!projectId) return Navigate to/projects /; return ProjectDetail projectId{projectId} /; } function ProjectDetail({ projectId }: { projectId: string }) { // The hook input stays string; loading/error are owned here — // see structure-early-return-render-branches. const { data, isLoading, error } useProject(projectId); // ... } function useProject(projectId: string) { return useQuery({ queryKey: [project, projectId], queryFn: () fetchProject(projectId), }); }这种父组件守卫 条件渲染子组件的结构有多个收益hook 输入类型永远是string调用方想传假值都过不了编译loading/error 归属清晰由子组件独立负责渲染分支与仓库规则 structure-early-return-render-branches.md 呼应同时天然满足本规则开头的去重要求——[project, projectId]相同的 queryKey 在多处共享同一请求。路径 B组件必须提前挂载时——用skipToken守卫查询函数当组件必须在参数出现前就保持挂载例如查询被另一个 flag 门控、参数由异步流程注入才允许把 hook 入参放宽为id?: string此时用skipToken守卫 queryFn而不是非空断言import { skipToken, useQuery } from tanstack/react-query; function useProject(projectId?: string, enabled true) { return useQuery({ queryKey: [project, projectId], queryFn: projectId ? () fetchProject(projectId) : skipToken, enabled, }); }为什么用skipToken而非enabled: false 非空断言skipToken是类型安全的查询禁用方式——当它被传给queryFn时TanStack Query 的 TS 类型会推导出data为undefined编译器会强制你处理数据尚不存在的分支而enabled: false只控制执行类型上仍认为data可用逼出data!之类的断言正是仓库规则体系坚决反对的写法参见 types-no-type-assertions.md。规则还特别提醒一个边界skipToken在参数缺失期间会禁用手动refetch()。如果调用方需要在缺失窗口内主动刷新就应当回到路径 A 在调用方收窄而不是为了迁就refetch而弱化 hook。总原则一句话严格 hook 保持严格——如果 hook 签名是id: string调用方就必须传真实 id。仓库里的 skipToken 实战上述模式在 Mastra 的 playground-ui 中有多处真实落地均严格遵循可选参数 skipToken守卫use-memory-thread-messages.tsMemory 线程消息分页查询export function useMemoryThreadMessages(threadId: string | undefined, opts?: { page?: number; perPage?: number }) { const client useMastraClient(); const page opts?.page ?? 0; const perPage opts?.perPage ?? 100; return useQuery({ queryKey: memoryThreadMessagesQueryKey(threadId, page), queryFn: threadId ? () client.getMemoryThread({ threadId }).listMessages({ page, perPage }) : skipToken, }); }这里的threadId可能来自尚未选中的列表项可为undefined因此 hook 接受可选参数而queryFn用三元表达式在参数缺失时退化为skipToken。queryKey 也由独立的memoryThreadMessagesQueryKey工厂函数生成[memory, thread, threadId, messages, page ?? 0] as const保证 key 结构统一、可被其他代码精确引用以执行invalidateQueries。同类的还有use-memory-status.tsMemory 状态查询参数不存在时同样走skipTokenuse-observational-memory.ts观测性 Memory 查询条件成立才执行queryFnuse-trace-insight.tstraceId undefined ? skipToken : () fetchTraceInsight(request, traceId)。这些 hooks 的测试也验证了去重 依赖参数的组合行为——memory-hooks.test.tsx、use-logs.msw.test.tsx、use-trace-spans.msw.test.tsx 等测试遵循仓库的 BDD 测试策略驱动真实的mastra/client-js React Query 栈只 mock 网络层绝不vi.mock自有 hooks/SDK见 testing-bdd-no-mocks.md。六、落地检查清单对照 client-request-dedupe.md 与仓库实践评审或编写 Mastra React 代码时依次确认数据是否通过useQuery消费同源数据绝不写useState useEffect fetch的组合queryKey 保持稳定、最小、可序列化。queryKey 是否准确描述请求标识参数全部进入 key如[project, projectId]常量性数据不放 key仅当 key 相同才能共享请求key 变更才触发新请求。不可变数据是否设置了staleTime: Infinity或按数据特征给定精确的staleTime如仓库中的30_000避免无意义的后台重取。写操作是否走useMutation并通过invalidateQueries联动相关查询刷新。依赖参数 hook 是否严格首选调用方守卫 条件渲染hook 签名保持id: string确需可选参数时用skipToken守卫queryFn绝不使用| null第三态、假值填充或非空断言。是否考虑了refetch与禁用态的交互skipToken禁用期间无手动refetch有此需求就在调用方收窄而非弱化 hook。这套模式让 Mastra 的 React 前端在多组件共享、列表分页、记忆回放、Trace 洞察等高频数据场景中把网络请求数压缩到理论最小值同时通过类型系统把数据缺失变成编译器可见的事实——去重与类型安全最终是一件事。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考