Svelte Query 的 createQueries：并行执行、动态追踪与合并多个查询结果的权威指南-北京尧图网络

Svelte Query 的 createQueries并行执行、动态追踪与合并多个查询结果的权威指南【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/query导读createQueries是 Svelte Querytanstack/svelte-query中用于并行执行多个查询的核心 Hook。它接收一个以响应式 Accessor 包裹的queries数组返回与输入顺序一一对应的查询结果数组并支持可选的combine函数将多个结果合并为单一派生值。读完本文你将掌握createQueries的完整签名、动态查询列表的响应式写法、combine合并模式以及其底层基于QueriesObserver的实现原理与类型推导机制。createQueries的函数参考页位于 docs/framework/svelte/reference/functions/createQueries.md其实现位于 packages/svelte-query/src/createQueries.svelte.ts。本文将以该参考页为主体骨架结合源码、类型定义与测试用例进行纵深扩充。一、函数签名与基本语义function createQueriesT, TCombinedResult(createQueriesOptions, queryClient?): TCombinedResult;Textends any[]代表queries中每一项查询选项的类型元组用于推导每个查询的返回类型。TCombinedResult默认等于T中每一项经GetCreateQueryResult映射后的结果数组如果传入了combine则为combine的返回类型。从源码看createQueries.svelte.ts 中实际导出的函数签名为export function createQueries T extends Arrayany, TCombinedResult QueriesResultsT, ( createQueriesOptions: Accessor{ queries: | readonly [...QueriesOptionsT] | readonly [...{ [K in keyof T]: GetCreateQueryOptionsForCreateQueriesT[K] }] combine?: (result: QueriesResultsT) TCombinedResult }, queryClient?: AccessorQueryClient, ): TCombinedResult返回的数组与传入的queries顺序一致——每一项对应同一下标的查询结果若提供了combine则返回combine的计算结果。该函数从 packages/svelte-query/src/index.ts 中导出并同时导出类型QueriesResults与QueriesOptionsindex.ts。二、核心参数详解1.createQueriesOptions必选类型为Accessor{ queries: ...; combine?: ... }即一个返回配置对象的函数。这里的AccessorT定义在 packages/svelte-query/src/types.tsexport type AccessorT () T即() T形式的函数。之所以把选项包裹在 Accessor 中是为了响应式——Svelte 5 的$derived会追踪 Accessor 内部读取的所有响应式状态如$props、$state当这些状态变化时queries数组会自动重建并重新同步观察者。配置对象包含两个字段queries必选查询选项数组。每一项与传给createQuery的选项结构一致queryKey、queryFn、staleTime、enabled、select等唯一的例外是placeholderData被特殊处理——在 createQueries.svelte.ts 中CreateQueryOptionsForCreateQueries将placeholderData的类型限定为TQueryFnData | QueriesPlaceholderDataFunctionTQueryFnData即函数形式的placeholderData永远只收到undefined参数。combine?可选(result: QueriesResultsT) TCombinedResult接收完整的结果数组返回任意合并后的值对象、标量均可。2.queryClient?可选类型为AccessorQueryClient。源码中通过useQueryClient(queryClient?.())createQueries.svelte.ts解析客户端如果显式传入则使用自定义QueryClient否则使用最近上下文QueryClientProvider中的默认实例。三、基础用法动态查询列表最典型的场景是根据一组 id 并行获取多条数据。参考页的第一个示例展示了完整写法script langts import { createQueries } from tanstack/svelte-query let { ids }: { ids: Arraynumber } $props() const postQueries createQueries(() ({ queries: ids.map((id) ({ queryKey: [post, id], queryFn: () fetchPost(id), staleTime: Infinity, })), })) /script ul {#each postQueries as query, index (ids[index])} {#if query.isPending} liLoading.../li {:else if query.isError} liError: {query.error.message}/li {:else} li{query.data.title}/li {/if} {/each} /ul要点拆解ids.map(...)在 Accessor 内部执行当父组件传入的ids属性变化时queries数组会随之重建createQueries自动为新增的 id 创建查询、为移除的 id 停止订阅。每个查询项是独立的createQuery语义queryKey、queryFn、staleTime等选项均与单查询一致。这里staleTime: Infinity表示数据永不过期避免重复请求。结果按序对应{#each postQueries as query, index}中index与ids下标对齐模板中的ids[index]用作 key保证列表 diff 时按 id 稳定复用 DOM 节点。query.isPending/query.isError/query.data每项结果拥有与createQuery相同的状态字段status、fetchStatus、data、error、refetch等。测试用例 packages/svelte-query/tests/createQueries/createQueries.svelte.test.ts 验证了这种逐项状态推进两个查询初始均为data: undefined依次 resolve 后result[0].data 1、result[1].data 2且每步都在$effect中产生一次可追踪的状态快照。动态增删查询createQueries特别擅长处理运行时变化的查询集合。测试 createQueries.svelte.test.ts 覆盖了「从空数组开始随后动态追加查询」的场景初始results为[[]]当queries.value被赋值为含一个查询的数组后createQueries自动为新查询发起请求并返回{ status: success, data: data1 }。这说明queries数组本身完全可以是响应式状态。四、combine将多个结果合并为单一值当页面需要基于多个查询结果统一决定渲染分支例如「全部加载完成才显示列表」时逐项判断状态会非常啰嗦。combine将整个结果数组折叠为一个派生值参考页第二个示例script langts import { createQueries } from tanstack/svelte-query let { ids }: { ids: Arraynumber } $props() const combined createQueries(() ({ queries: ids.map((id) ({ queryKey: [post, id], queryFn: () fetchPost(id), })), combine: (postQueries) ({ data: postQueries.map((query) query.data), isPending: postQueries.some((query) query.isPending), isError: postQueries.some((query) query.isError), }), })) /script {#if combined.isPending} Loading... {:else if combined.isError} Error loading posts {:else} ul {#each combined.data as post} li{post?.title}/li {/each} /ul {/if}几个关键点combine收到的是完整结果数组可以自由使用map、some、every、flatMap等数组方法聚合。返回值类型完全自定义这里返回的是{ data, isPending, isError }对象createQueries的返回类型TCombinedResult自动变为该对象类型。合并后模板只有一个分支出口把「部分成功部分失败」的复杂判断收敛到三个布尔值模板可读性显著提升。测试 createQueries.svelte.test.ts 验证了合并行为的增量更新初始queries.res resolve 第一个查询后变为first result再 resolve 第二个后变为first result,second result且最终对象仍带有combined: true标记。combine 中的响应式追踪与 refetchcombine内部访问的字段会被精细追踪。测试 createQueries.svelte.test.ts 展示了两个进阶行为只在访问的属性变化时重渲染combine中只读取query.data通过flatMap因此仅data变化触发更新同一次 refetch 中isFetching的中间过渡不会产生额外渲染。合并结果中可以暴露函数combine可返回refetch: () Promise.all(queryResults.map((res) res.refetch()))把多个查询的刷新操作打包成一个调用且当 refetch 后数据未变化时不会产生多余的重新渲染results.length保持不变。五、源码原理createQueries 是如何工作的理解实现能帮助你预判响应式行为。完整实现见 packages/svelte-query/src/createQueries.svelte.ts核心流程如下1. 解析 QueryClient 与恢复状态const client $derived(useQueryClient(queryClient?.())) const isRestoring useIsRestoring()client是响应式派生值显式传入的queryClient优先否则取自最近上下文。isRestoring用于服务端渲染 / 缓存恢复场景HydrationBoundary见 useIsRestoring.ts。2. 响应式解析查询选项const { queries, combine } $derived.by(createQueriesOptions) const resolvedQueryOptions $derived( queries.map((opts) { const resolvedOptions client.defaultQueryOptions(opts) resolvedOptions._optimisticResults isRestoring.current ? isRestoring : optimistic return resolvedOptions }), )$derived.by(createQueriesOptions)这是响应式的入口。Accessor 内部读取的响应式状态一旦变化queries与combine自动重建。client.defaultQueryOptions(opts)将用户选项与QueryClient的全局默认选项合并默认staleTime、retry等。_optimisticResults标记乐观结果模式。isRestoring期间为isRestoring否则为optimistic这决定了结果在订阅前的初始状态计算方式避免恢复期间误触发请求。3. 基于 QueriesObserver 观察所有查询const observer $derived( new QueriesObserverTCombinedResult(client, resolvedQueryOptions, combine), )createQueries复用了 query-core 的QueriesObserver单一观察者统一管理多个QueryObserver这也是它与createQuery走QueryObserver的根本区别。注释特别说明因为QueriesObserver没有setOptions方法无法像createMutation那样复用观察者实例因此当选项变化时通过$derived重建观察者。4. 乐观结果订阅更新function createResult() { const [_, getCombinedResult, trackResult] observer.getOptimisticResult( resolvedQueryOptions, combine, ) return getCombinedResult(trackResult()) } const [results, update] createRawRefTCombinedResult(createResult()) $effect(() { const unsubscribe isRestoring.current ? () undefined : observer.subscribe(() update(createResult())) return unsubscribe }) $effect.pre(() { observer.setQueries(resolvedQueryOptions, { combine }) update(createResult()) })getOptimisticResulttrackResult在首次渲染尚未订阅时就能基于缓存计算出正确结果实现「无闪烁」首帧。createRawRef底层容器见 containers.svelte.ts以非深响应式的方式持有结果数组避免对结果对象做不必要的代理。$effect订阅isRestoring期间跳过订阅恢复数据由 hydrate 注入不应触发请求否则订阅QueriesObserver每次状态变化重新计算合并结果。$effect.pre同步选项在 DOM 更新前调用observer.setQueries同步最新的queries与combine并立即刷新结果。这套「$derived解析选项 → 观察者重建 → 乐观结果渲染 → 订阅增量更新」的流程与单查询的基础实现 createBaseQuery.svelte.ts 保持一致的架构风格但针对多查询做了专门优化。5. 恢复期间的请求抑制isRestoring期间的「不 fetch」行为有专门的集成测试IsRestoring.svelte 配合 createQueries.svelte.test.ts当isRestoring为 true 时即使时间流逝queryFn也一次都不会被调用状态保持pending、fetchStatus保持idle直至恢复期结束。六、类型系统深度逐项类型推导createQueries的类型签名在 createQueries.svelte.ts 中由两个递归工具类型驱动QueriesOptionsT把查询选项元组T递归映射为CreateQueryOptionsForCreateQueries元组递归深度上限MAXIMUM_DEPTH 20createQueries.svelte.ts用于规避超大数组字面量导致的 TS 深度限制。QueriesResultsT把选项元组递归映射为结果元组GetCreateQueryResultT保持「下标对齐」的类型关系。GetCreateQueryResultcreateQueries.svelte.ts按三种方式解析每一项的类型显式对象形式{ queryFnData, error, data }、显式元组形式[TQueryFnData, TError, TData]、以及从queryFn/select/throwOnError推断的隐式形式。GetDefinedOrUndefinedQueryResultcreateQueries.svelte.ts当查询项设置了initialData值或返回值的函数结果类型自动提升为DefinedCreateQueryResult此时data不再是undefined。类型层面的行为有专门的test-d.ts类型测试佐证createQueries.test-d.ts混合类型的动态数组[...ArrayCreateQueryResultnumber, Error, CreateQueryResultboolean, Error]这样的展开元组可以精确推导L15-L44。元组类型参数createQueries[[number], [string], [Arraystring, boolean]]显式指定每一项的类型data/error的类型与结果一一对应L46-L82。TData优先级当元组为[TQueryFnData, TError, TData]时第三位TData优先于第一位TQueryFnDataselect的入参与返回也会被正确约束L84-L114。七、与 createQuery 的分工与选型建议createQueries与 createQuery 的区别在于查询数量是否静态可知场景推荐 API单个静态查询createQuery固定数量如 2~3 个的并行查询多个createQuery或createQueries均可数量动态变化依赖 id 列表、分页、勾选项createQueries响应式重建查询集合需要把多个结果聚合成单一渲染状态createQueriescombine希望多个查询共享一个统一刷新入口createQueriescombine暴露refetch选型上的几个实践建议不要在createQuery内部循环调用对每个 id 手动调用createQuery违反 Hooks 固定顺序约定且无法随数据增删自动管理生命周期createQueries内部由QueriesObserver统一管理增删查询只需改变 Accessor 内返回的数组。依赖型查询enabled同样适用每个查询项可以独立设置enabledcombine中也能按需过滤isPending例如用isLoading区分「禁用」与「加载中」参考 createQuery 参考页中的 dependent query 示例。数据共享受益于统一缓存多个查询项使用相同queryKey前缀时如[post, id]天然复用 QueryCache 的queryKey哈希与去重机制相同 key 不会重复请求。八、小结createQueries是 Svelte Query 中面向「多查询并行」的一等公民响应式Accessor 包裹的选项让queries数组随状态自动增删无需手动清理按序返回结果数组与输入顺序一一对应{#each}渲染天然友好可合并combine将 N 个结果折叠为单一派生值类型自动推导有源码与测试背书实现上复用 query-core 的QueriesObserver配合$derived与乐观结果机制实现无闪烁更新createQueries.svelte.test.ts 与 createQueries.test-d.ts 覆盖了状态推进、动态增删、combine 追踪、恢复期抑制与类型推导等关键行为。当你的 Svelte 应用中需要「一组查询」而非「一个查询」时createQueries就是那个把复杂性封装在响应式内核中的标准答案。【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/query创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Svelte Query 的 createQueries：并行执行、动态追踪与合并多个查询结果的权威指南

相关推荐

生信数据库检索脚本零基础入门：不写代码也能批量下载

Nacos V3 HTTP API 规范全景解读：受众分级、路径契约、鉴权与统一响应设计

RustDesk认证优化：矩阵算法提升安全与性能

更多资讯

磁粉芯技术解析：新能源与电力电子的核心材料

CVAT 接入第三方模型：4 步在标注画布上跑出检测框

SpringBoot电竞商城系统架构设计与高并发实践

磁场测量技术与霍尔传感器优化实践

Zephyr RTOS 快速入门：一份代码框架跑通上千块开发板

开源项目商业化：五大黄金赛道与实战策略

今日更新

CopilotKit Vue Demo 与 React Demo 的 Parity 实现指南：路由、运行时端点与交互语义的全框架对齐

Harbor RBAC 实战：db_auth 模式下非管理员用户管理项目成员的完整验证与权限模型解析

STM32平衡车纯平衡程序从拆包到参数整定的完整调试指南

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？