TanStack Query ESLint 规则 no-void-query-fn 深度解析：如何用类型感知检查拦截“返回 void 的 queryFn”

TanStack Query ESLint 规则 no-void-query-fn 深度解析如何用类型感知检查拦截“返回 void 的 queryFn”【免费下载链接】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/queryTanStack Query 的queryFn的返回值会被写入缓存并暴露给订阅者一旦它实际返回void/undefined组件拿到的将永远是空数据且这类错误往往难以在运行时察觉。本文基于仓库内的官方规则文档 no-void-query-fn.md 与其实现源码 no-void-query-fn.rule.ts完整讲解tanstack/eslint-plugin-query中no-void-query-fn规则的动机、正误示例、类型感知检测原理、覆盖的 API 边界与接入配置帮助你把这类“忘记 return”的隐患拦截在静态检查阶段。规则动机queryFn 必须返回可被缓存的值规则文档开篇给出的核心约束是Query functions must return a value that will be cached by TanStack Query. Functions that dont return a value (void functions) can lead to unexpected behavior and might indicate a mistake in the implementation.即queryFn必须返回一个会被 TanStack Query 缓存的值。不返回值的函数void 函数会导致不可预期的行为通常意味着实现上的失误。一个典型的失误场景是在异步函数里await了网络请求却忘记把结果return出去——请求确实发出了但缓存里写入的是undefined界面表现为“请求成功但数据为空”这类 bug 在运行时很难定位。错误示例规则文档给出的incorrect代码/* eslint tanstack/query/no-void-query-fn: error */ useQuery({ queryKey: [todos], queryFn: async () { await api.todos.fetch() // Function doesnt return the fetched data }, })正确示例对应的correct写法显式把请求结果返回/* eslint tanstack/query/no-void-query-fn: error */ useQuery({ queryKey: [todos], queryFn: async () { const todos await api.todos.fetch() return todos }, })规则属性Recommended推荐启用在插件预设中默认以error级别开启不可自动修复Not Fixable规则只做报告不提供 auto-fix。这一点可以从插件入口 index.ts 的预设配置得到印证recommendedRules中显式声明了tanstack/query/no-void-query-fn: error并被recommended、recommendedStrict、flat/recommended、flat/recommended-strict四套预设统一引用规则自身 meta 中也标注了recommended: error见 规则实现。实现原理一只对导入 tanstack/*-query 的文件生效规则本体通过工具函数detectTanstackQueryImports包装规则实现 L27。该函数位于 detect-react-query-imports.ts其逻辑是监听文件中的ImportDeclaration节点仅当导入来源以tanstack/开头且以-query结尾且为 value 导入时记录该导入的所有命名导入将原始规则指令与检测指令合并到同一个 listener 中执行。因此该规则天然具备“作用域隔离”特性只有真正从tanstack/react-query、tanstack/vue-query、tanstack/solid-query、tanstack/svelte-query、tanstack/svelte-query等框架包引入 API 的文件才会被检查同名的业务函数不会触发误报。实现原理二定位 queryFn 属性并做类型检查规则的核心监听器挂在Property节点上规则实现 L29-L67判断条件是父节点必须是对象字面量ASTUtils.isObjectExpression(node.parent)属性键必须是名为queryFn的标识符ASTUtils.isIdentifierWithName(node.key, queryFn)。命中后再执行一次“类型信息可用性检查”const parserServices context.sourceCode.parserServices if ( !parserServices || !parserServices.esTreeNodeToTSNodeMap || !parserServices.program ) { return }从源码结构看这是一条类型感知type-aware规则只有当 ESLint 使用typescript-eslint/parser并开启项目感知解析即parserOptions.project或projectService使 TypeScript 程序与类型映射可用时规则才会工作缺少类型服务时会静默跳过而不是报错。具备类型服务后规则获取queryFn值表达式的 TypeScript 类型取第一个调用签名并读取其返回类型const checker parserServices.program.getTypeChecker() const tsNode parserServices.esTreeNodeToTSNodeMap.get(node.value) const type checker.getTypeAtLocation(tsNode) if (type.getCallSignatures().length 0) { const returnType type.getCallSignatures()[0]?.getReturnType() if (!returnType) return if (isIllegalReturn(checker, returnType)) { context.report({ node: node.value, messageId: noVoidReturn }) } }报错消息固定为queryFn must return a non-undefined valuemessageIdnoVoidReturn报告位置指向queryFn的属性值节点。isIllegalReturnawait 解包 联合类型递归判定逻辑集中在 isIllegalReturnfunction isIllegalReturn(checker: TypeChecker, type: Type): boolean { const awaited checker.getAwaitedType(type) if (!awaited) return false if (awaited.isUnion()) { return awaited.types.some((t) isIllegalReturn(checker, t)) } const typeString checker.typeToString(awaited) return typeString void || typeString undefined }三个关键设计决定了规则的精度checker.getAwaitedType(type)先对返回类型做 await 解包。Promisevoid会先解包为void再比对因此无论是同步返回void、返回Promisevoid、还是async函数隐式返回Promisevoid都能被统一识别联合类型递归若解包后的类型是联合类型例如{ data: string } | undefined只要其中任一成员是void/undefined即视为非法——这对应测试中“三元表达式某分支返回 undefined”“if 分支缺少 return 隐式产生 undefined”等 case字符串精确比对最终通过typeToString只匹配void与undefined两个精确字符串。这意味着null、0、false这类“合法但 falsy”的数据类型不会误报测试用例queryFn returns null、queryFn returns 0、queryFn returns false均列为 valid。测试用例揭示的覆盖范围与边界no-void-query-fn.test.ts 使用typescript-eslint/rule-tester并显式配置parserOptions: { project: true, tsconfigRootDir: ts-fixture }来保证类型感知环境其 valid/invalid 用例恰好勾勒出规则的完整能力边界覆盖的 API 面invalid 用例中均会报错调用面是否检查useQuery/useInfiniteQuery/useSuspenseQuery✅ 报错queryOptions工厂函数中的 queryFn✅ 报错queryClient.fetchQuery/prefetchQuery✅ 报错queryClient.prefetchInfiniteQuery/ensureQueryData/ensureInfiniteQueryData✅ 报错由于规则只看“对象字面量中键名为queryFn的属性”并不绑定外层调用者所以上述所有接受queryFn的入口都被自然覆盖——这是一个从源码结构看得到的泛化收益新增的 Query API 只要沿用queryFn选项名无需改规则即可继续受检。会被判为非法的形态均触发noVoidReturn同步/异步函数体无 return隐式undefined/void显式声明(): Promisevoid() Promise.resolve(undefined)传入外部定义的async function voidOperation(): Promisevoid作为queryFn类型检查基于实参类型而非字面量形态条件分支中“一个分支返回数据、另一分支缺失 return”三元表达式其中一个分支为undefined联合类型递归命中;try/catch中 try 分支有 return、catch 分支无 return隐式undefined并入联合类型。不会被误报的形态返回对象、Promise数据、Promise.resolve(数据)、显式PromiseData/ 泛型PromiseResponseT外部 async 函数返回Promise{ data: string }返回null、0、false返回数字枚举、字符串枚举、const enum成员以及 async 函数返回枚举成员useInfiniteQuery正常返回页数据、prefetch*/ensure*返回r.json()等。这些用例共同说明规则的目标是**“返回类型在 await 解包后仍含 void/undefined 成员”**而不是粗暴地要求“必须有 return 语句”。接入方式与适用前提该规则随 npm 包tanstack/eslint-plugin-query发布package.json当前仓库内版本 5.102.8规则在 rules.ts 中注册。使用时的关键前提与配置需要 TypeScript 类型信息。由于规则依赖parserServices.program与esTreeNodeToTSNodeMapESLint 必须使用typescript-eslint/parser并配置项目感知parserOptions.project: true或projectService。缺少类型服务时规则静默不检查不会导致 lint 崩溃——但也意味着漏报。版本兼容范围包声明的 peerDependencies 为eslint ^8.57.0 || ^9.0.0 || ^10.0.0typescript ^5.6.0 || ^6.0.0 || ^7.0.0可选见 package.json在纯 JS无类型服务项目中该规则实际不生效。启用方式直接采用预设即可规则已包含在推荐集中且级别为error// flat config import query from tanstack/eslint-plugin-query export default [query.configs[flat/recommended]]若只想单独启用/调整该规则可在rules中显式声明tanstack/query/no-void-query-fn: error。无选项、不可自动修复规则schema: []不接受任何配置项且由于“补上 return”涉及业务意图判断meta 未提供 fixer文档 Attributes 中标注 Fixable 未勾选修复需人工处理。小结规则的设计取舍no-void-query-fn体现了 TanStack Query ESLint 插件的一条设计主线用类型系统换取静态检查的深度。它以对象字面量中queryFn键名为锚点借getAwaitedType统一处理同步/异步返回再对联合类型做递归判定从而在不依赖代码形态内联函数、外部函数引用、工厂函数、queryClient命令式 API的情况下准确识别“会缓存出空值”的 queryFn。同时它通过导入检测限定作用域、通过类型服务可用性检查保证降级安全配合预设默认error级别使“忘记 return 请求结果”这一 TanStack Query 项目中最隐蔽的失误类别在 lint 阶段即可被稳定捕获。【免费下载链接】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），仅供参考