TanStack Query Angular 实战用 queryOptions 集中管理并类型安全地复用查询配置【免费下载链接】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本文围绕 TanStack Query 仓库中的 Angular 指南 Query Options 展开讲解如何在tanstack/angular-query-experimental中用queryOptions把查询配置queryKeyqueryFn等抽取为可复用、类型安全的共享对象并深入源码说明其重载类型设计、queryKey数据标签机制以及如何与injectQuery、QueryClient配合完成组件内外的一致消费。读完本文你将掌握在 Angular 应用中建立查询配置服务层的完整模式从服务内集中定义到组件响应式消费再到组件外通过QueryClient读写缓存全部保持编译期类型安全。一、queryOptions 解决什么问题在没有queryOptions之前同一个查询的queryKey和queryFn往往要在多个组件中重复书写而一旦你在某处手写[post, postId]这个 keyTypeScript 无法知道它对应的是什么数据结构getQueryData、setQueryData等操作也就退化为unknown。queryOptions的定位就是允许以类型安全的方式共享和复用查询配置并且会把queryKey打上来自queryFn返回值的类型标签源码 JSDoc 原文ThequeryKeywill be tagged with the type fromqueryFn见 query-options.ts。值得注意的是从源码看它的运行时实现极其简单// packages/angular-query-experimental/src/query-options.ts export function queryOptions(options: unknown) { return options }它是一个纯粹的类型层函数运行时原样返回传入对象对应测试断言expect(queryOptions(object)).toBe(object)见 query-options.test.ts没有任何运行时开销。它的价值全部体现在 TypeScript 的类型重载与queryKey标签上下文第四节展开。二、服务模式在 QueriesService 中集中定义查询配置指南给出的核心示例是把查询配置集中到一个Injectable服务中仓库中的示例工程 query-options-from-a-service 完整实现了该模式运行方式见其 READMEpnpm install后pnpm start。服务实现见 queries-service.tsimport { Injectable, inject } from angular/core import { lastValueFrom } from rxjs import { queryOptions } from tanstack/angular-query-experimental import { HttpClient } from angular/common/http export interface Post { id: number title: string body: string } Injectable({ providedIn: root, }) export class QueriesService { private readonly http inject(HttpClient) post(postId: number) { return queryOptions({ queryKey: [post, postId], queryFn: () { return lastValueFrom( this.http.getPost( https://jsonplaceholder.typicode.com/posts/${postId}, ), ) }, }) } posts() { return queryOptions({ queryKey: [posts], queryFn: () lastValueFrom( this.http.getArrayPost( https://jsonplaceholder.typicode.com/posts, ), ), }) } }几个要点参数化 keypost(postId)以方法参数构造queryKey同一个配置工厂可以服务任意文章 IDkey 的粒度与参数一一对应天然获得按 ID 的缓存隔离。RxJS 到 Promise 的桥接HttpClient返回ObservablelastValueFrom将其转换为PromisePost符合queryFn的约定。类型推断自动完成http.getPost(...)的泛型参数经queryFn一路推断到queryOptions的返回类型post(1)返回的配置对象中queryKey已被标注为数据结构为Post调用方无需任何显式类型标注。三、组件内消费input.required injectQuery指南示例的第二部分展示了组件如何消费服务中的配置并顺带演示了与QueryClient的交互// 文档示例docs/framework/angular/guides/query-options.md postId input.required({ transform: numberAttribute, }) queries inject(QueriesService) postQuery injectQuery(() this.queries.post(this.postId())) queryClient.query(this.queries.post(23)).catch(noop) queryClient.setQueryData(this.queries.post(42).queryKey, newPost)仓库示例中 post.component.ts 是这份代码的完整落地Component({ changeDetection: ChangeDetectionStrategy.OnPush, selector: post, templateUrl: ./post.component.html, imports: [RouterLink], }) export default class PostComponent { private readonly queries inject(QueriesService) readonly postId input.required({ transform: numberAttribute, }) readonly postQuery injectQuery(() this.queries.post(this.postId())) }这里有三个值得展开的细节injectQuery接收的是函数() this.queries.post(this.postId())。从 inject-query.ts 的 JSDoc 可以看到传入的函数会在响应式上下文中运行will be run in the reactive context类似于computed当postId信号变化时工厂函数重新求值queryKey随之变化查询自动切换到新 key 并复用缓存。因此input信号必须带()调用文档示例中的this.postId缺调用请以示例工程为准。input.required({ transform: numberAttribute })模板传入的是字符串属性numberAttribute转换器把它变成数字后进入queryKey避免[post, 1]与[post, 1]这类 key 不一致问题。结果全是信号injectQuery返回的CreateQueryResult中data、isLoading、error等字段均为Signal由 types.ts 中的MapToSignals映射实现模板可直接写postQuery.data()配合OnPush变更检测策略。列表组件 posts.component.ts 则展示了最简单的消费形态——injectQuery(() this.queries.posts())一行即完成订阅同时inject(QueryClient)表明缓存客户端本身也可注入供组件外场景使用。四、源码剖析三重载与 queryKey 数据标签queryOptions之所以能做到零运行时成本却全程类型安全关键在于 query-options.ts 中基于initialData与queryFn形态拆分的三个重载重载类型适用条件关键约束DefinedInitialDataOptions提供了非 undefined的initialDataqueryFn变为可选调用方拿到defined结果data信号不会是undefinedUnusedSkipTokenOptionsqueryFn使用了skipToken禁用查询queryFn被收窄为排除SkipToken的真实函数结果data为unknownUndefinedInitialDataOptions常规场景queryFn必填initialData可以是值、函数或undefined函数形式允许返回undefined用于条件性初始数据三个重载的返回值都叠加了同一个标签类型DefinedInitialDataOptions... QueryKeyWithDataTagTQueryKey, TQueryFnData, TErrorQueryKeyWithDataTag通过query-core的dataTagSymbol把一个不可见的符号属性挂在queryKey上其值就是queryFn的返回数据结构。类型测试文件 query-options.test-d.ts 直接验证了这一机制const { queryKey: tagged } queryOptions({ queryKey: key, queryFn: () Promise.resolve(5), }) assertTypenumber(tagged[dataTagSymbol])正是这个标签让第二节的组件外读写缓存成为可能const { queryKey } queryOptions({ queryKey: [key], queryFn: () Promise.resolve(5), }) const data queryClient.getQueryData(queryKey) // ^? number | undefined queryClient.setQueryData(queryKey, (prev) prev) // prev: number | undefined类型测试进一步确认getQueryData返回number | undefinedL163-L174setQueryData传入错误类型的值如字符串5会直接触发编译错误L192-L209。此外若配置中没有queryFn标签会退化为unknownL143-L150即未声明数据来源的 key 只能以unknown访问缓存这是有意为之的保守设计。queryOptions返回的配置对象还可以直接喂给QueryClient的实例方法类型测试覆盖了这些用法见 query-options.test-d.tsnew QueryClient().fetchQuery(options)→Promisenumbernew QueryClient().query(options)→Promisenumber且select生效select: (data) data.toString()时返回Promisestring配合enabled: false或queryFn: skipToken时类型行为正确skipToken场景下结果为Promiseunknown这说明配置即对象的抽象在组件injectQuery与组件外fetchQuery/query/getQueryData/setQueryData是统一且可互换的。五、类型推断与配置覆盖在共享配置上扩展 select指南的第二个示例展示了共享配置的一个重要特性调用点可以展开并覆盖字段且类型推断仍然成立// Type inference still works, so query.data will be the return type of select instead of queryFn queries inject(QueriesService) query injectQuery(() ({ ...groupOptions(1), select: (data) data.title, }))由于queryOptions返回的就是普通选项对象运行时return options在调用点用对象展开合并再传入injectQuery是完全合法的select的类型会沿着重载传导——query.data信号的类型是select的返回类型data.title即string而不是queryFn的原始类型。这一推断链有类型测试佐证const options queryOptions({ queryKey: [key], queryFn: () Promise.resolve(5), select: (data) data.toString(), }) const data new QueryClient().query(options) assertTypePromisestring(data)见 query-options.test-d.ts需要注意的边界是queryKey上的数据标签仍然基于queryFn的返回类型而非select的类型类型测试should tag the queryKey with the result type of the QueryFn if select is usedL152-L161确认标签值为number而非string——即缓存层存的始终是原始数据select只影响观察层。另外CreateQueryOptions的基础类型继承自QueryObserverOptions去掉suspense字段见 types.ts因此staleTime、refetchInterval、enabled、retry、placeholderData等所有观察者选项都可以在服务配置中或调用点覆盖时直接使用同时类型测试should not allow excess properties确认了选项对象会进行精确的属性检查不会出现拼写错误的静默忽略。六、实践建议与相关文件结合上述源码与测试给出几条可直接落地的实践建议一个服务按实体域聚合配置如QueriesService.post(postId)/posts()的写法key 构造与请求逻辑同址维护避免 key 漂移。组件内用injectQuery(() service.method(deps))把输入信号作为工厂参数传入保证响应式重取组件外需要触发一次查询并拿到 Promise时用queryClient.query(options)或fetchQuery(options)并记得.catch(noop)之类的错误处理文档示例即演示了queryClient.query(this.queries.post(23)).catch(noop)。预热缓存走setQueryData(options.queryKey, ...)带标签的queryKey保证写入值与queryFn返回类型一致文档示例queryClient.setQueryData(this.queries.post(42).queryKey, newPost)。适用前提本文基于tanstack/angular-query-experimental包的当前仓库实现示例工程使用 Angular 的inject、input等新 API具体版本能力以仓库中 packages/angular-query-experimental/package.json 声明为准。本文涉及的关键文件指南原文docs/framework/angular/guides/query-options.md核心实现packages/angular-query-experimental/src/query-options.ts、packages/angular-query-experimental/src/types.ts、packages/angular-query-experimental/src/inject-query.ts、导出入口 packages/angular-query-experimental/src/index.ts测试packages/angular-query-experimental/src/tests/query-options.test.ts、packages/angular-query-experimental/src/tests/query-options.test-d.ts示例工程examples/angular/query-options-from-a-service含 queries-service.ts、post.component.ts、posts.component.ts【免费下载链接】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），仅供参考
TanStack Query Angular 实战：用 queryOptions 集中管理并类型安全地复用查询配置
TanStack Query Angular 实战用 queryOptions 集中管理并类型安全地复用查询配置【免费下载链接】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本文围绕 TanStack Query 仓库中的 Angular 指南 Query Options 展开讲解如何在tanstack/angular-query-experimental中用queryOptions把查询配置queryKeyqueryFn等抽取为可复用、类型安全的共享对象并深入源码说明其重载类型设计、queryKey数据标签机制以及如何与injectQuery、QueryClient配合完成组件内外的一致消费。读完本文你将掌握在 Angular 应用中建立查询配置服务层的完整模式从服务内集中定义到组件响应式消费再到组件外通过QueryClient读写缓存全部保持编译期类型安全。一、queryOptions 解决什么问题在没有queryOptions之前同一个查询的queryKey和queryFn往往要在多个组件中重复书写而一旦你在某处手写[post, postId]这个 keyTypeScript 无法知道它对应的是什么数据结构getQueryData、setQueryData等操作也就退化为unknown。queryOptions的定位就是允许以类型安全的方式共享和复用查询配置并且会把queryKey打上来自queryFn返回值的类型标签源码 JSDoc 原文ThequeryKeywill be tagged with the type fromqueryFn见 query-options.ts。值得注意的是从源码看它的运行时实现极其简单// packages/angular-query-experimental/src/query-options.ts export function queryOptions(options: unknown) { return options }它是一个纯粹的类型层函数运行时原样返回传入对象对应测试断言expect(queryOptions(object)).toBe(object)见 query-options.test.ts没有任何运行时开销。它的价值全部体现在 TypeScript 的类型重载与queryKey标签上下文第四节展开。二、服务模式在 QueriesService 中集中定义查询配置指南给出的核心示例是把查询配置集中到一个Injectable服务中仓库中的示例工程 query-options-from-a-service 完整实现了该模式运行方式见其 READMEpnpm install后pnpm start。服务实现见 queries-service.tsimport { Injectable, inject } from angular/core import { lastValueFrom } from rxjs import { queryOptions } from tanstack/angular-query-experimental import { HttpClient } from angular/common/http export interface Post { id: number title: string body: string } Injectable({ providedIn: root, }) export class QueriesService { private readonly http inject(HttpClient) post(postId: number) { return queryOptions({ queryKey: [post, postId], queryFn: () { return lastValueFrom( this.http.getPost( https://jsonplaceholder.typicode.com/posts/${postId}, ), ) }, }) } posts() { return queryOptions({ queryKey: [posts], queryFn: () lastValueFrom( this.http.getArrayPost( https://jsonplaceholder.typicode.com/posts, ), ), }) } }几个要点参数化 keypost(postId)以方法参数构造queryKey同一个配置工厂可以服务任意文章 IDkey 的粒度与参数一一对应天然获得按 ID 的缓存隔离。RxJS 到 Promise 的桥接HttpClient返回ObservablelastValueFrom将其转换为PromisePost符合queryFn的约定。类型推断自动完成http.getPost(...)的泛型参数经queryFn一路推断到queryOptions的返回类型post(1)返回的配置对象中queryKey已被标注为数据结构为Post调用方无需任何显式类型标注。三、组件内消费input.required injectQuery指南示例的第二部分展示了组件如何消费服务中的配置并顺带演示了与QueryClient的交互// 文档示例docs/framework/angular/guides/query-options.md postId input.required({ transform: numberAttribute, }) queries inject(QueriesService) postQuery injectQuery(() this.queries.post(this.postId())) queryClient.query(this.queries.post(23)).catch(noop) queryClient.setQueryData(this.queries.post(42).queryKey, newPost)仓库示例中 post.component.ts 是这份代码的完整落地Component({ changeDetection: ChangeDetectionStrategy.OnPush, selector: post, templateUrl: ./post.component.html, imports: [RouterLink], }) export default class PostComponent { private readonly queries inject(QueriesService) readonly postId input.required({ transform: numberAttribute, }) readonly postQuery injectQuery(() this.queries.post(this.postId())) }这里有三个值得展开的细节injectQuery接收的是函数() this.queries.post(this.postId())。从 inject-query.ts 的 JSDoc 可以看到传入的函数会在响应式上下文中运行will be run in the reactive context类似于computed当postId信号变化时工厂函数重新求值queryKey随之变化查询自动切换到新 key 并复用缓存。因此input信号必须带()调用文档示例中的this.postId缺调用请以示例工程为准。input.required({ transform: numberAttribute })模板传入的是字符串属性numberAttribute转换器把它变成数字后进入queryKey避免[post, 1]与[post, 1]这类 key 不一致问题。结果全是信号injectQuery返回的CreateQueryResult中data、isLoading、error等字段均为Signal由 types.ts 中的MapToSignals映射实现模板可直接写postQuery.data()配合OnPush变更检测策略。列表组件 posts.component.ts 则展示了最简单的消费形态——injectQuery(() this.queries.posts())一行即完成订阅同时inject(QueryClient)表明缓存客户端本身也可注入供组件外场景使用。四、源码剖析三重载与 queryKey 数据标签queryOptions之所以能做到零运行时成本却全程类型安全关键在于 query-options.ts 中基于initialData与queryFn形态拆分的三个重载重载类型适用条件关键约束DefinedInitialDataOptions提供了非 undefined的initialDataqueryFn变为可选调用方拿到defined结果data信号不会是undefinedUnusedSkipTokenOptionsqueryFn使用了skipToken禁用查询queryFn被收窄为排除SkipToken的真实函数结果data为unknownUndefinedInitialDataOptions常规场景queryFn必填initialData可以是值、函数或undefined函数形式允许返回undefined用于条件性初始数据三个重载的返回值都叠加了同一个标签类型DefinedInitialDataOptions... QueryKeyWithDataTagTQueryKey, TQueryFnData, TErrorQueryKeyWithDataTag通过query-core的dataTagSymbol把一个不可见的符号属性挂在queryKey上其值就是queryFn的返回数据结构。类型测试文件 query-options.test-d.ts 直接验证了这一机制const { queryKey: tagged } queryOptions({ queryKey: key, queryFn: () Promise.resolve(5), }) assertTypenumber(tagged[dataTagSymbol])正是这个标签让第二节的组件外读写缓存成为可能const { queryKey } queryOptions({ queryKey: [key], queryFn: () Promise.resolve(5), }) const data queryClient.getQueryData(queryKey) // ^? number | undefined queryClient.setQueryData(queryKey, (prev) prev) // prev: number | undefined类型测试进一步确认getQueryData返回number | undefinedL163-L174setQueryData传入错误类型的值如字符串5会直接触发编译错误L192-L209。此外若配置中没有queryFn标签会退化为unknownL143-L150即未声明数据来源的 key 只能以unknown访问缓存这是有意为之的保守设计。queryOptions返回的配置对象还可以直接喂给QueryClient的实例方法类型测试覆盖了这些用法见 query-options.test-d.tsnew QueryClient().fetchQuery(options)→Promisenumbernew QueryClient().query(options)→Promisenumber且select生效select: (data) data.toString()时返回Promisestring配合enabled: false或queryFn: skipToken时类型行为正确skipToken场景下结果为Promiseunknown这说明配置即对象的抽象在组件injectQuery与组件外fetchQuery/query/getQueryData/setQueryData是统一且可互换的。五、类型推断与配置覆盖在共享配置上扩展 select指南的第二个示例展示了共享配置的一个重要特性调用点可以展开并覆盖字段且类型推断仍然成立// Type inference still works, so query.data will be the return type of select instead of queryFn queries inject(QueriesService) query injectQuery(() ({ ...groupOptions(1), select: (data) data.title, }))由于queryOptions返回的就是普通选项对象运行时return options在调用点用对象展开合并再传入injectQuery是完全合法的select的类型会沿着重载传导——query.data信号的类型是select的返回类型data.title即string而不是queryFn的原始类型。这一推断链有类型测试佐证const options queryOptions({ queryKey: [key], queryFn: () Promise.resolve(5), select: (data) data.toString(), }) const data new QueryClient().query(options) assertTypePromisestring(data)见 query-options.test-d.ts需要注意的边界是queryKey上的数据标签仍然基于queryFn的返回类型而非select的类型类型测试should tag the queryKey with the result type of the QueryFn if select is usedL152-L161确认标签值为number而非string——即缓存层存的始终是原始数据select只影响观察层。另外CreateQueryOptions的基础类型继承自QueryObserverOptions去掉suspense字段见 types.ts因此staleTime、refetchInterval、enabled、retry、placeholderData等所有观察者选项都可以在服务配置中或调用点覆盖时直接使用同时类型测试should not allow excess properties确认了选项对象会进行精确的属性检查不会出现拼写错误的静默忽略。六、实践建议与相关文件结合上述源码与测试给出几条可直接落地的实践建议一个服务按实体域聚合配置如QueriesService.post(postId)/posts()的写法key 构造与请求逻辑同址维护避免 key 漂移。组件内用injectQuery(() service.method(deps))把输入信号作为工厂参数传入保证响应式重取组件外需要触发一次查询并拿到 Promise时用queryClient.query(options)或fetchQuery(options)并记得.catch(noop)之类的错误处理文档示例即演示了queryClient.query(this.queries.post(23)).catch(noop)。预热缓存走setQueryData(options.queryKey, ...)带标签的queryKey保证写入值与queryFn返回类型一致文档示例queryClient.setQueryData(this.queries.post(42).queryKey, newPost)。适用前提本文基于tanstack/angular-query-experimental包的当前仓库实现示例工程使用 Angular 的inject、input等新 API具体版本能力以仓库中 packages/angular-query-experimental/package.json 声明为准。本文涉及的关键文件指南原文docs/framework/angular/guides/query-options.md核心实现packages/angular-query-experimental/src/query-options.ts、packages/angular-query-experimental/src/types.ts、packages/angular-query-experimental/src/inject-query.ts、导出入口 packages/angular-query-experimental/src/index.ts测试packages/angular-query-experimental/src/tests/query-options.test.ts、packages/angular-query-experimental/src/tests/query-options.test-d.ts示例工程examples/angular/query-options-from-a-service含 queries-service.ts、post.component.ts、posts.component.ts【免费下载链接】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），仅供参考
