WordPress.com Dashboard 数据层实战：基于 TanStack Query 的 REST 数据获取与状态管理指南

前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载本文以 client/dashboard/docs/data-library.md 为骨架系统讲解 WordPress.com 前端项目 wp-calypso 中 dashboard仪表盘数据层Data Library的设计与实现。读者将掌握dashboard 如何以 TanStack Query前身 React Query替代 Redux 承担服务端状态管理、如何通过automattic/api-core与automattic/api-queries双层包组织 REST API 数据获取、如何使用路由加载器Route Loader预取数据以及在组件层通过useQuery/useSuspenseQuery消费缓存数据。Dashboard 数据层概览为何放弃 Reduxdashboard 的数据获取与状态管理采用一套轻量策略服务端状态全部交给 TanStack Query 管理避免引入 Redux改用更直接的、基于 Hooks 的方式处理 UI 状态。这套方案的定位与适用场景在>import { fetchDomainSuggestions, type DomainSuggestion } from automattic/api-core; const domainSuggestions await fetchDomainSuggestions( example search );也可以由查询层包装后通过useQuery消费。api-core 的函数约定为一律异步并返回Promise取数函数以fetch前缀命名写操作以create、update、delete、add、remove等动词开头函数应尽量原样返回端点响应仅允许最小化转换例如端点恒返回{ success: true }时可简化为返回void。共享 queryClient加载器与组件的缓存同源文档特别强调加载器与组件之间复用的是同一批查询缓存之所以共享是因为它们共用automattic/api-queries导出的同一个queryClient。这个实例的默认行为在 query-client.ts 中有明确配置staleTime: 0刻意使用 TanStack 默认值因为 a8c 各类 dashboard 的数据可能被多处修改例如 wp-admin 侧切换 Tab 时应视为过期数据refetchOnWindowFocus: true、refetchOnMount: true对应本地缓存优先 聚焦/挂载刷新的缓存策略retry对 4xxstatus 400 status 500错误不重试其余错误最多重试 3 次支持本地持久化通过createSyncStoragePersister把查询缓存写入localStoragekey 为REACT_QUERY_OFFLINE_CACHEmaxAge为 24 小时cacheDataShapeVersion在查询数据结构变化时递增getPersistQueryClientPromise( userId )按用户维度恢复/持久化缓存buster使用${cacheDataShapeVersion}-${userId}支持会话support session时不落盘clearQueryClient()用于清除缓存。此外该文件还导出了ApiQueriesMutationMeta.statId与ApiQueriesQueryMeta.persist两个扩展元数据接口并对 TanStack 的Register做了模块声明增强——这是实现变更统计标识与按查询控制持久化的类型基础。路由加载器Route Loader预取模式dashboard 最主要的取数模式是在路由加载器中预取数据、渲染组件前数据已就绪。文档给出的siteSettingsPHPRoute是一个完整范例先通过siteBySlugQuery( siteSlug )拿到站点对象再用hasHostingFeature判断站点是否具备 PHP 托管能力只有具备时才进一步预取 PHP 版本数据const siteSettingsPHPRoute createRoute( { getParentRoute: () siteRoute, path: settings/php, loader: async ( { params: { siteSlug } } ) { const site await queryClient.ensureQueryData( siteBySlugQuery( siteSlug ) ); if ( hasHostingFeature( site, HostingFeatures.PHP ) ) { await queryClient.ensureQueryData( sitePHPVersionQuery( site.ID ) ); } }, } ).lazy( () import( ../sites/settings-php ).then( ( d ) createLazyRoute( site-settings-php )( { component: () d.default siteSlug{ siteRoute.useParams().siteSlug } /, } ) ) );关键点是queryClient.ensureQueryData它先检查数据是否已在缓存中未命中才发起请求从而避免不必要的网络往返。这里还能看到两个数据层约定路由懒加载.lazy() 动态import把路由组件拆包按需加载以优化首屏体积dashboard 路由统一采用该模式可参考 router.md条件预取用能力判断feature flag决定是否预取避免对不适用场景发无效请求。从源码看sitePHPVersionQuery的真实定义site-php-version.ts正是文档所述的构建器模式export const sitePHPVersionQuery ( siteId: number ) queryOptions( { queryKey: [ site, siteId, php-version ], queryFn: () fetchPHPVersion( siteId ), } );查询键采用[ site, siteId, php-version ]三段式结构资源域 站点 ID 具体资源这与 api-core 中fetchPHPVersion( siteId )的调用一一对应。组件级查询useSuspenseQuery 与 useQuery在组件层数据通过 TanStack Query 的 Hook 消费。文档给出了两类典型场景。场景一消费加载器已预取的数据useSuspenseQueryconst { data: currentVersion } useSuspenseQuery( { ...sitePHPVersionQuery( site.ID ), enabled: hasHostingFeature( site, HostingFeatures.PHP ), } );展开构建器后补充enabled选项组件级条件配合 Suspense 特性组件挂载时数据已在缓存中由路由加载器预取因此不会触发额外的等待状态。这里体现了查询构建器的一个设计原则不要把自己的专属选项写进查询定义——enabled属于组件特定行为应由组件展开后传入api-queries README 中siteWordPressVersionQuery配enabled: site.is_wpcom_staging_site的示例与此一致。场景二组件按需动态加载useQueryconst { data: siteContentSummary, isLoading } useQuery( siteResetContentSummaryQuery( site.ID ) );siteResetContentSummaryQuery同样来自 api-queriessite-reset.tsexport const siteResetContentSummaryQuery ( siteId: number ) queryOptions( { queryKey: [ site, siteId, reset, content-summary ], queryFn: () fetchSiteResetContentSummary( siteId ), } );这类查询仅在某组件真正需要时才触发配合isLoading展示加载态适合低频、局部化的数据。变更Mutation与缓存失效写操作同样在 api-queries 中以mutationOptions构建且必须遵守statId规范详见下文。以 PHP 版本更新为例export const sitePHPVersionMutation ( siteId: number ) mutationOptions( { meta: { statId: site-php-version-update }, mutationFn: ( version: string ) updatePHPVersion( siteId, version ), onSuccess: () { queryClient.invalidateQueries( sitePHPVersionQuery( siteId ) ); }, } );变更成功后通过共享的queryClient.invalidateQueries使对应查询失效下一次读取即会重新拉取——这正是加载器与组件共享同一queryClient带来的直接收益。查询与变更的编写规范可复用性保证api-queries README 给出了一套保证跨组件复用性的硬性约定理解这些约定有助于读懂 dashboard 中的每一个查询一律返回queryOptions()/mutationOptions()的结果两者运行时是 no-op但能显著改善 TypeScript 类型推断——select、onSuccess回调中的data参数类型会被自动推导无需手写易错的参数类型。不要在查询定义中使用select因为queryClient.ensureQueryData()预取时不会应用select会导致 loader 缓存的数据与组件期望不一致。若查询只想要数据子集应在queryFn内转换如isSiteUsingBlockThemeQuery在queryFn中返回themes[ 0 ]?.is_block_theme ?? false若仅某个组件需要子集则在组件侧传select如从sitePurchasesQuery( site.ID )中find出 DIFM 套餐。不要在查询定义中塞入单点使用选项enabled等由组件传入。除非必要如refetchOnMount避免覆盖查询选项防止开发者不理解选项含义就复制粘贴。每个 mutation 必须设置meta.statId命名规则为先名词后动词site-plugin-activate而非activate-site-plugin用于失败统计归组ID 不得超过 28 字符过长短语需缩写如two-step-auth→2fa。api-queries/src/tests/mutation-stat-ids.test.ts 会断言每个 mutation 都有statId、无重复、且不超限。onSuccess/onError只做查询失效与缓存更新额外的业务逻辑如埋点recordTracksEvent( calypso_settings_updated )放在组件调用侧。正确写法是把onSuccess回调作为mutate调用的第二个参数传入而不是在useMutation展开时覆盖 mutation 选项里定义的回调——后者会破坏包内预设的缓存更新逻辑。路由加载器与组件查询的协作边界结合 router.md 可以更完整地理解两者的分工路由层用loader: () queryClient.ensureQueryData( userSettingsQuery() )预取进入页面即需要的数据组件随后用useQuery( userSettingsQuery() )读取同一份缓存。需要额外授权校验的路由如个人资料页可用beforeLoad钩子做权限检查不满足时跳转例如检测到two_step_reauthorization_required时重定向到重新认证页。经验性的选型建议从文档与源码结构可以推断凡是路由切换后立刻要展示的数据站点信息、版本、设置走路由加载器预取凡是组件局部、低频、可延迟加载的数据如重置内容摘要用组件级useQuery需要 Suspense 渲染体验的用useSuspenseQuery写操作统一走带statId的 mutation 构建器并依赖invalidateQueries刷新共享缓存。小结wp-calypso 的 dashboard 数据层是一套REST API 双层包 TanStack Query的轻量方案automattic/api-core负责 REST 取数与类型定义automattic/api-queries在其上提供共享queryClient与查询/变更构建器路由加载器通过ensureQueryData预取并共享缓存组件通过useQuery/useSuspenseQuery按需消费缓存策略本地优先、聚焦刷新、24 小时持久化与错误重试策略由query-client.ts统一收敛。对于需要扩展 dashboard 数据能力的开发者建议按序阅读 api-core/README.md、api-queries/README.md 以及 router.md再对照 api-queries/src 中的资源文件如 site-php-version.ts、site-reset.ts套用既有模式新增查询与路由。赞分享前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载相关推荐TanStack Start 集成 TanStack Query基于 React Query 的全栈数据获取与 SSR 实战指南TanStack Start 集成 TanStack Query基于 React Query 的全栈数据获取与 SSR 实战指南 导读 本文基于当前仓库中的官前端路由SSRReact Starter Kit 前端状态管理实战TanStack Query tRPC Jotai 的分层数据获取架构React Starter Kit 前端状态管理实战TanStack Query tRPC Jotai 的分层数据获取架构 本文是 react sta后端前端Vue Querytanstack/vue-query实战指南Vue 应用中异步数据的获取、缓存与状态管理Vue Querytanstack/vue query实战指南Vue 应用中异步数据的获取、缓存与状态管理 Vue Query 是 TanStack Q前端缓存状态管理上一篇Sa-Token 最新版本说明与 Maven 依赖引入实战指南下一篇AWS CLI 创建私有 CA 实战深入解析 acm-pca create-certificate-authority 命令创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考