TanStack QueryPreact Query类型别名 AnyUseMutationOptions如何在辅助函数中接收任意 mutation 配置【免费下载链接】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导读在编写 Preact Query 应用时useMutation带有四个泛型参数跨组件复用配置或抽取通用辅助函数时类型往往成为阻碍。AnyUseMutationOptions是 TanStack Query 面向 Preact 预置的类型别名它将 UseMutationOptions 的全部泛型参数置为any专用于接收任意 mutation 配置但又不关心具体类型的封装场景。本文将结合仓库源码逐层拆解该类型的定义、四个泛型参数的业务含义、它与其他Any*查询选项的关系以及正确的使用边界。类型定义与仓库中的位置该类型的完整定义极其精简仅一行type AnyUseMutationOptions UseMutationOptionsany, any, any, any;其在仓库中的定义位于 packages/preact-query/src/types.ts:400。源码在声明上方写明了用途{link UseMutationOptions} with all type parameters set toany, useful when the specific types arent relevant, e.g. when accepting options for any mutation in a helper function.即当某个函数只负责接受并透传任意 mutation 的选项而不关心该 mutation 的具体数据类型时就可以用AnyUseMutationOptions作为参数类型。由于 preact-query 包的入口文件通过export * from ./types整体导出了 types 模块见 packages/preact-query/src/index.ts:7因此该类型别名与 UseMutationOptions、UseMutationResult 等一样是面向使用方暴露的公开类型可直接从tanstack/preact-query导入import type { AnyUseMutationOptions } from tanstack/preact-query需要留意的是搜索整个 packages 目录可以发现AnyUseMutationOptions在仓库中只出现在 preact-query 与 react-query 两处定义点preact-query 自身运行时代码并未在内部消费它。它本质上是一个面向库使用者的便捷公共类型其价值在读者自己的辅助函数与高阶封装中体现。深入底层UseMutationOptions 的四个泛型参数AnyUseMutationOptions是 UseMutationOptions 的实例化结果。要真正理解它省掉了什么先要看UseMutationOptions本身的完整签名packages/preact-query/src/types.ts:411-419export interface UseMutationOptions TData unknown, TError DefaultError, TVariables void, TOnMutateResult unknown, extends OmitKeyof MutationObserverOptionsTData, TError, TVariables, TOnMutateResult, _defaulted {}它本质上是 query-core 中MutationObserverOptions的同构体仅通过OmitKeyof剔除了仅供框架内部使用的_defaulted字段。四个泛型参数在源码 JSDoc 中有明确分工泛型参数默认值含义TDataunknown你的mutationFn成功解析resolve后返回的数据类型TErrorDefaultErrormutationFn可能抛出的错误类型TVariablesvoid调用mutate/mutateAsync时传入的变量variables类型TOnMutateResultunknownonMutate返回值的类型会作为context参数传给onSuccess/onError/onSettled——常用于携带乐观更新所需的回滚数据而AnyUseMutationOptions UseMutationOptionsany, any, any, any正是把这四个参数一键放宽为any的预置别名。与之配套的还有一批同族Any类型别名均定义于同一文件 packages/preact-query/src/types.ts例如AnyUseBaseQueryOptions第 27 行五个参数全部为anyAnyUseQueryOptions第 153 行AnyUseSuspenseQueryOptions第 178 行它们的 JSDoc 措辞一致——all type parameters set toany, useful when the specific types arent relevant可见这是该类型族统一的设计惯例。为什么需要全部设为 any的类型正常使用useMutation时类型系统会帮你推导出一整套严格约束。例如const mutation useMutationPost, Error, { title: string }({ mutationFn: createPost, // ... })此时mutate只接受{ title: string }data会被推导为Post。这套约束在组件内非常有用但当你写的是与具体数据类型解耦的通用逻辑时它反而成为负担。典型场景包括辅助函数参数一个工具函数需要接收任意 mutation 的配置但只负责转发或做通用处理如统一日志、统一 loading 计数不关心mutationFn到底返回什么。高阶组件 / 配置中心集中式保存、注册、重放一组 mutation 配置使用方可能是任意业务。跨模块的类型标注与 mutationOptions 配合时需要给尚未指定具体业务类型的公共配置变量标注类型。在上述场景中写全泛型没有意义——因为你不知道、也不想知道调用方传入的 mutation 具体操作什么数据。AnyUseMutationOptions正是为此准备的惰性逃生舱import type { AnyUseMutationOptions } from tanstack/preact-query import { useMutation, mutationOptions } from tanstack/preact-query // 一个接收任意 mutation 配置的通用注册函数 function registerMutation(options: AnyUseMutationOptions) { // 通用处理透传 / 记录 / 登记 mutationKey 等 return options } // 任意业务配置都可以传入而无需先声明具体泛型 const opts registerMutation( mutationOptions({ mutationKey: [posts, create], mutationFn: createPost, // 假设 createPost: (v: { title: string }) PromisePost }), ) // 后续使用时仍可交给 useMutation 重新获得完整类型推导 function CreatePostButton() { const mutation useMutation(opts) return button onClick{() mutation.mutate({ title: Hello })}创建/button }需要说明的是AnyUseMutationOptions放宽的只是类型参数它并没有把 options 对象本身的结构抹平。mutationFn、mutationKey、variables、onSuccess、onError、onMutate、retry、gcTime等由MutationObserverOptions定义的字面字段依然存在只是字段内嵌的数据类型变成了any。因此在接受并转发的环节它是安全的——真正的类型检查仍然发生在最终调用useMutation/mutate的边界处。它如何与 useMutation / mutationOptions / useMutationState 协同AnyUseMutationOptions不是孤立存在的它服务于 Preact Query mutation 的完整 API 族useMutation接收参数类型为UseMutationOptionsTData, TError, TVariables, TOnMutateResult见 packages/preact-query/src/useMutation.ts:198。由于类型参数是协变的传入方传入AnyUseMutationOptions完全可以被接受——这也是上面示例能够编译的原因。mutationOptions它的两个重载分别要求必须带mutationKey与不需要mutationKey但二者接受的都还是UseMutationOptions...见 packages/preact-query/src/mutationOptions.ts:34-97。该 helper 原样返回传入对象用途是让同一份配置可同时供useMutation执行、供useMutationState按mutationKey检索。若要在公共配置仓库层做标注AnyUseMutationOptions正是合身的选择。useMutationState通过filters如mutationKey、status观察全局 mutation 状态天然与具体数据类型无关是AnyUseMutationOptions场景最常见的下游消费者。仓库在 mutationOptions.ts:15-32 给出了一个真实的组合示例先通过mutationOptions({ mutationKey, mutationFn })定义配置再用useMutationState监听同一个mutationKey是否处于pending用于渲染全局的Saving…指示器。若把这段逻辑抽成可复用的通用组件例如接收任意 mutation 配置并显示其进行状态参数类型就可以声明为AnyUseMutationOptions。使用边界与类型安全权衡该别名是一把双刃剑使用时应把握分寸适合接受并透传/仅做通用处理的地方。在中间层使用AnyUseMutationOptions让类型检查下沉到真正执行 mutation 的业务边界是最佳实践。不要把any再向外扩散。若你的函数最终要消费data、error或构造variables则应在边界处重新声明具体泛型。源码中UseMutationOptions的四个默认值unknown/DefaultError/void/unknown其实已经提供了一版宽松但不失体面的基线AnyUseMutationOptions是比默认值更彻底的放弃约束选项仅应在确实无法或无需确定类型时使用。之所以mutate/mutateAsync/onMutate相关的类型同样被放宽是因为这四个any最终也流入了 UseMutationResult、UseMutateFunction、UseMutateAsyncFunction 等派生类型见 types.ts:432-458。也就是说一旦中途使用AnyUseMutationOptions下游从mutate拿到的variables与onSuccess里的data也会是any需要在使用点重新收窄。跨框架对照与 React Query 的定义保持同构该类型并非 Preact 独有。在 React 生态的对应实现中packages/react-query/src/types.ts:401 存在完全相同的声明export type AnyUseMutationOptions UseMutationOptionsany, any, any, any两个包的 types 模块结构一致AnyUseQueryOptions、AnyUseMutationOptions等别名也都同步提供。如果你在 React 与 Preact 之间迁移代码这类Any类型别名可以直接平移语义与用法完全相同。这也印证了 TanStack Query 各框架适配层共享同一套类型设计语言核心泛型约束来自tanstack/query-core各框架只在其上加薄薄一层 hook 语义。总结AnyUseMutationOptions用一行别名替开发者处理了为不确定的 mutation 标注类型的琐事。把它放在整个类型体系里看底层的 UseMutationOptions 定义了四维泛型约束数据、错误、变量、乐观更新上下文mutationOptions 负责让同一份配置可被复用与观测而AnyUseMutationOptions则是这三者之间的连接胶水——在跨越未知业务类型的通用层给出一个不撒谎、可编译、易读写的中间类型。掌握它的适用边界你的 mutation 封装代码就能既保持类型推导的锋利又不至于在通用逻辑中被具体的类型绊住手脚。相关源码与文档索引类型定义packages/preact-query/src/types.ts:396-419React 同构实现packages/react-query/src/types.ts:401类型导出入口packages/preact-query/src/index.ts:7mutationOptions 实现packages/preact-query/src/mutationOptions.tsuseMutation 实现packages/preact-query/src/useMutation.ts类型测试佐证packages/preact-query/src/tests/useMutation.test-d.tsx、packages/preact-query/src/tests/mutationOptions.test-d.tsx参考文档UseMutationOptions 接口、UseMutationResult 类型、useMutation、useMutationState【免费下载链接】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），仅供参考