Preact Query 的 usePrefetchQuery在渲染階段預(yù)取數(shù)據(jù)、消除 Suspense 請(qǐng)求瀑布【免費(fèi)下載鏈接】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.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/qu/queryusePrefetchQuery是tanstack/preact-query提供的一個(gè)無返回值voidHook專用于在渲染期間、Suspense 邊界之前提前觸發(fā)一次查詢預(yù)取讓下游使用useSuspenseQuery的組件無需等待即可拿到緩存數(shù)據(jù)。讀完本文你將掌握它的完整簽名與類型參數(shù)、options 配置約束以及它是如何在源碼層面做到已有緩存即跳過、只請(qǐng)求一次、不產(chǎn)生瀑布的。本文的講解主體是 usePrefetchQuery 參考文檔同時(shí)對(duì)照其真實(shí)實(shí)現(xiàn) usePrefetchQuery.tsx、類型定義 types.ts 與測(cè)試用例 usePrefetchQuery.test.tsx 做縱深展開。適用背景Suspense 渲染模式下為何需要渲染期預(yù)取在 Preact 生態(tài)中使用 TanStack Query 時(shí)useSuspenseQuery會(huì)讓組件在數(shù)據(jù)未就緒時(shí)掛起suspend由外層Suspense展示 fallback。如果數(shù)據(jù)請(qǐng)求只能等到組件掛起后才發(fā)起那么嵌套多層的 Suspense 組件就會(huì)形成串行的請(qǐng)求瀑布request waterfall每一層都要等上一層的數(shù)據(jù)返回并完成渲染后才能開始發(fā)起自己的請(qǐng)求。usePrefetchQuery正是為了打破這種串行等待而生它把發(fā)起請(qǐng)求的動(dòng)作提前到渲染函數(shù)體內(nèi)執(zhí)行。由于它不讀取數(shù)據(jù)、不返回任何內(nèi)容也不會(huì)導(dǎo)致掛起因此可以在 Suspense 邊界之上、甚至在整棵子樹渲染之前就讓多個(gè)查詢并行進(jìn)入 in-flight 狀態(tài)。關(guān)于該問題背景可進(jìn)一步閱讀 請(qǐng)求瀑布指南。從包的導(dǎo)出列表可以確認(rèn)它是一等公民 API在 index.ts 中與useSuspenseQuery、usePrefetchInfiniteQuery等一起被導(dǎo)出。函數(shù)簽名入?yún)?、返回與類型參數(shù)參考文檔給出如下簽名function usePrefetchQueryTQueryFnData, TError, TData, TQueryData, TQueryKey(options, queryClient?): void;完整定義位于 usePrefetchQuery.tsx:42。需要注意的核心定位有三點(diǎn)usePrefetchQuery不返回任何內(nèi)容返回類型是void。它只負(fù)責(zé)在渲染期間發(fā)射一次預(yù)取請(qǐng)求其結(jié)果寫入查詢緩存由后續(xù)消費(fèi)數(shù)據(jù)的 Hook 讀取。典型調(diào)用位置是在一個(gè)包裹著使用useSuspenseQuery組件的 Suspense 邊界之前/之上。此時(shí)預(yù)取已經(jīng)發(fā)起等下層組件真正掛起并讀取緩存時(shí)數(shù)據(jù)往往已經(jīng)就緒。你可以向它傳遞一切能傳給queryClient.query的選項(xiàng)但其中queryKey始終必填而queryFn在未定義默認(rèn)查詢函數(shù)default query function時(shí)也是必填的。五個(gè)泛型參數(shù)與默認(rèn)值泛型參數(shù)默認(rèn)值含義TQueryFnDataunknownqueryFn解析出的數(shù)據(jù)類型TErrorErrorqueryFn可能拋出的錯(cuò)誤類型源碼中通過 query-core 的DefaultError別名表達(dá)見 usePrefetchQuery.tsx:44TDataTQueryFnData經(jīng)select轉(zhuǎn)換后的data類型未使用select時(shí)即TQueryFnDataTQueryDataTQueryFnData實(shí)際存入查詢緩存的數(shù)據(jù)類型即select與placeholderData的輸入通常與TQueryFnData相同TQueryKeyreadonly unknown[]即QueryKeyqueryKey的類型由于usePrefetchQuery從不把data讀出來使用所以這些泛型更多是為了讓傳入的 options 對(duì)象保持類型安全并允許同一份 options 在別處被復(fù)用。參數(shù)說明options 與可選的 queryClientoptionsUsePrefetchQueryOptionsoptions的類型是 UsePrefetchQueryOptions其底層結(jié)構(gòu)定義于 types.ts:79export type UsePrefetchQueryOptions... DistributiveOmit QueryExecuteOptionsTQueryFnData, TError, TData, TQueryData, TQueryKey, queryFn { queryFn?: Exclude..., SkipToken }翻譯成直覺上的語義就是queryFn之外的任何queryClient.query選項(xiàng)如queryKey、staleTime、gcTime、retry、networkMode等都可以原樣傳入。兩個(gè)類型層面的約束值得注意queryKey始終是必填的——參考文檔中明確說明即便其他選項(xiàng)都可選預(yù)取也必須知道把結(jié)果寫入哪條查詢。queryFn在類型上是可選的但實(shí)際總是需要真的能跑起來其類型被Exclude..., SkipToken處理意味著skipToken不允許作為這里的值——預(yù)取必須有實(shí)際的查詢函數(shù)可執(zhí)行除非已經(jīng)通過queryClient配置了默認(rèn)查詢函數(shù)可參考 默認(rèn)查詢函數(shù)指南。若既無queryFn又無默認(rèn)查詢函數(shù)調(diào)用將無法真正發(fā)起請(qǐng)求。queryClient自定義實(shí)例第二個(gè)參數(shù)queryClient是可選的QueryClient。當(dāng)你不傳它時(shí)usePrefetchQuery會(huì)像其他所有 query Hook 一樣從最近的 Context 中讀取QueryClient當(dāng)你需要繞過 Context、顯式指定某個(gè)實(shí)例時(shí)直接傳入即可。在源碼實(shí)現(xiàn)中這一解析邏輯發(fā)生在 usePrefetchQuery.tsx:58 的const client useQueryClient(queryClient)。其語義由 QueryClientProvider.tsx:21 的useQueryClient決定優(yōu)先返回顯式傳入的實(shí)例否則取QueryClientContext中的值如果兩者都沒有會(huì)拋出錯(cuò)誤No QueryClient set, use QueryClientProvider to set one。因此應(yīng)用根部通常需要用 QueryClientProvider 注入 client它也負(fù)責(zé)在掛載/卸載時(shí)調(diào)用client.mount()/client.unmount()。源碼透視預(yù)取為什么廉價(jià)且不會(huì)重復(fù)請(qǐng)求usePrefetchQuery的全部實(shí)現(xiàn)只有幾行卻集中體現(xiàn)了其全部語義。核心代碼在 usePrefetchQuery.tsx:58-62const client useQueryClient(queryClient) if (!client.getQueryState(options.queryKey)) { void client.query(options).catch(noop) }可以拆解出三個(gè)關(guān)鍵機(jī)制冪等跳過if (!client.getQueryState(options.queryKey))只有在這條 query 當(dāng)前不存在任何緩存狀態(tài)時(shí)預(yù)取才會(huì)真正執(zhí)行。文檔明確強(qiáng)調(diào)只要緩存里已有狀態(tài)——包括上一次嘗試遺留的pending或error狀態(tài)——預(yù)取就會(huì)被跳過。因此把usePrefetchQuery放在一個(gè)會(huì)在每次渲染都執(zhí)行的組件里是廉價(jià)且安全的它不會(huì)重新拉取已經(jīng)在緩存中、或已經(jīng)在途in-flight的數(shù)據(jù)。直接調(diào)用底層client.query(options)傳入的 options 被原樣交給queryClient.query執(zhí)行這正是你能傳給queryClient.query的一切都能傳給它的實(shí)現(xiàn)來源。請(qǐng)求失敗時(shí)錯(cuò)誤會(huì)被寫入該 query 的緩存狀態(tài)而不是在 Hook 內(nèi)部被吞掉或拋出——失敗的錯(cuò)誤信息由后續(xù)真正掛起讀取的useSuspenseQuery組件負(fù)責(zé)呈現(xiàn)見下文測(cè)試用例 3。void ... .catch(noop)吸收 promise由于 Hook 不向調(diào)用方暴露任何結(jié)果執(zhí)行client.query(options)得到的 promise 無人消費(fèi)catch(noop)用于避免在并發(fā)執(zhí)行期間出現(xiàn)未處理的 promise rejection。noop是從tanstack/query-core導(dǎo)入的空操作函數(shù)見 usePrefetchQuery.tsx:1。標(biāo)準(zhǔn)用法在 Suspense 邊界之前觸發(fā)預(yù)取參考文檔給出的示例完整地展示了推薦用法。預(yù)取被放在渲染函數(shù)體頂部早于包裹Posts的Suspenseimport { Suspense } from preact/compat import { usePrefetchQuery } from tanstack/preact-query function App() { // 在渲染期間觸發(fā)預(yù)取早于下面的 suspense 邊界。 usePrefetchQuery({ queryKey: [posts], queryFn: fetchPosts, }) return ( Suspense fallback{h1Loading posts.../h1} Posts / /Suspense ) }其效果是App一渲染[posts]查詢就已開始在后臺(tái)拉取Posts組件內(nèi)部通過useSuspenseQuery參考 useSuspenseQuery 文檔讀取同一queryKey時(shí)要么直接命中已就緒的緩存瞬間完成渲染要么至多只展示一次 fallback等待時(shí)間與先發(fā)請(qǐng)求再渲染路徑一致但無需串行。若同時(shí)預(yù)取多條查詢它們會(huì)并行發(fā)起從根本上消除嵌套 Suspense 結(jié)構(gòu)下的請(qǐng)求瀑布。行為契約由測(cè)試用例驗(yàn)證的五個(gè)邊界倉庫中的行為測(cè)試 usePrefetchQuery.test.tsx 把上述語義固化成了一套可驗(yàn)證的契約分別對(duì)應(yīng)如下場(chǎng)景查詢狀態(tài)不存在時(shí)發(fā)起預(yù)取第 33 行頁面先展示Loading...fallback計(jì)時(shí)推進(jìn)后渲染出data: prefetchQuery且queryFn只被調(diào)用一次——說明usePrefetchQuery與useSuspenseQuery共享同一條緩存后掛起的消費(fèi)者不會(huì)重復(fù)請(qǐng)求。查詢狀態(tài)已存在時(shí)跳過預(yù)取第 68 行預(yù)先通過queryClient.query填充緩存后再掛載包含usePrefetchQuery的組件樹queryFn不會(huì)被再次調(diào)用頁面直接渲染出既有數(shù)據(jù)。這印證了每次渲染都調(diào)用它也很廉價(jià)的設(shè)計(jì)承諾。錯(cuò)誤會(huì)向下傳遞且不重取失敗查詢第 103 行當(dāng)查詢?cè)?jīng)失敗、緩存中殘留error狀態(tài)時(shí)usePrefetchQuery會(huì)跳過該查詢錯(cuò)誤最終由ErrorBoundary呈現(xiàn)為Oops!而不是由預(yù)取靜默重試或再次發(fā)起請(qǐng)求。在 Suspense 邊界內(nèi)部使用也不會(huì)死循環(huán)第 148 行即使把usePrefetchQuery放進(jìn)與掛起組件共享的 Suspense 子樹內(nèi)由于狀態(tài)一旦存在即跳過渲染循環(huán)不會(huì)反復(fù)觸發(fā)新的請(qǐng)求queryFn同樣只執(zhí)行一次。錯(cuò)誤可被重置后重新拉取第 182 行當(dāng)預(yù)取路徑上遺留了error狀態(tài)導(dǎo)致組件始終掛起在錯(cuò)誤上時(shí)通過useQueryErrorResetBoundary見 參考文檔的reset配合ErrorBoundary的onReset清空邊界后預(yù)取可以重新生效并成功拉取——驗(yàn)證了錯(cuò)誤恢復(fù)路徑。此外還有一個(gè)專門針對(duì)瀑布場(chǎng)景的測(cè)試第 242 行App中連續(xù)調(diào)用三次usePrefetchQuery預(yù)取嵌套組件各自的數(shù)據(jù)測(cè)試斷言渲染開始后三條查詢的fetchStatus全部立即為fetching并行在途整個(gè)過程中 Suspense 的Fallback只渲染一次最終三個(gè)嵌套組件幾乎同時(shí)展示數(shù)據(jù)——這是預(yù)取能消滅瀑布的直接證據(jù)。相關(guān) API 與延伸閱讀usePrefetchQuery并不是孤立存在的它與下面這些 API 共同構(gòu)成 Suspense 預(yù)取體系無限查詢的對(duì)應(yīng)物usePrefetchInfiniteQuery 參考文檔 提供同樣的渲染期預(yù)取能力用于useSuspenseInfiniteQuery其選項(xiàng)類型為 types.ts:117 處的UsePrefetchInfiniteQueryOptions。正式指南Prefetching 指南 系統(tǒng)介紹預(yù)取在該框架中的整體策略請(qǐng)求瀑布指南 則專門討論它要解決的問題形態(tài)。消費(fèi)端 HookuseSuspenseQuery、useSuspenseQueries非 Suspense 場(chǎng)景下的等效替代是經(jīng)典的 useQuery。相關(guān)選項(xiàng)類型UseSuspenseQueryOptions 與 UseBaseQueryOptions 可幫助你理解queryClient.query選項(xiàng)的完整集合。小結(jié)總結(jié)下來usePrefetchQuery是一個(gè)零返回值、渲染期副作用式的 API在 Suspense 邊界之上盡早并行發(fā)起請(qǐng)求讓下游useSuspenseQuery組件直接命中熱緩存內(nèi)部通過getQueryState判斷實(shí)現(xiàn)有狀態(tài)即跳過的冪等語義配以catch(noop)吸收未消費(fèi)的 promise。其實(shí)際行為已被倉庫內(nèi)的 6 組測(cè)試完整固化從只請(qǐng)求一次失敗不重試錯(cuò)誤可恢復(fù)到消除三層嵌套瀑布都有據(jù)可查可以直接作為你在項(xiàng)目中編排預(yù)取邏輯時(shí)的行為參照?！久赓M(fèi)下載鏈接】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.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/qu/query創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考