Relay 查询刷新（Refreshing Queries）实战指南：基于 useQueryLoader 与 useLazyLoadQuery 实现数据实时更新

Relay 查询刷新Refreshing Queries实战指南基于 useQueryLoader 与 useLazyLoadQuery 实现数据实时更新【免费下载链接】relayRelay is a JavaScript framework for building>项目地址: https://gitcode.com/gh_mirrors/relay29/relay在 Relay 应用中刷新refreshing一个查询指的是用完全相同的查询与变量重新从服务器获取这份查询最初渲染时所使用的数据以获得该数据的最新版本。这篇指南面向使用 Relay 17 的 React 开发者围绕useQueryLoader/loadQuery与useLazyLoadQuery两条主路径讲清楚两种常见做法直接走网络刷新、以及避免 Suspense 隐藏已渲染内容的fetchQuery组合方案并结合仓库源码说明fetchPolicy、fetchKey的底层机制帮助你按需选择最合适的刷新方案。刷新查询前先考虑实时数据能力在动手写定期手动刷新逻辑之前首先应该判断是否应该优先使用实时real-time能力来保持数据与服务器同步。实时能力可以在无需手动周期性刷新数据的情况下自动让数据保持最新。一个典型的例子是使用GraphQL Subscriptions订阅它可以让服务器在数据发生变化时主动推送更新从而彻底省去客户端主动刷新的需求。当然使用订阅通常需要在服务器端做额外配置支持订阅类型的 GraphQL 操作在客户端的 网络层 做相应配置例如配置 WebSocket 传输与订阅处理逻辑。如果实时能力不适用例如服务器不支持订阅、或刷新频率很低不值得维护订阅连接再考虑下面两种基于 Hook 的查询刷新方案。关于刷新 Fragment 的对应场景可参考 refreshing-fragments本指南聚焦于查询query级别的刷新。使用useQueryLoader/loadQuery刷新查询在 Fetching Queries for Render 一节中我们介绍了useQueryLoaderHook它用于在渲染之前以render-as-you-fetch的方式加载并保留查询引用。使用它刷新查询非常简单再次调用loadQuery即可。/** * App.react.js */ const AppQuery require(__generated__/AppQuery.graphql); function App(props: Props) { const [queryRef, loadQuery] useQueryLoader( AppQuery, props.appQueryRef /* initial query ref */ ); const refresh useCallback(() { // Load the query again using the same original variables. // Calling loadQuery will update the value of queryRef. // The fetchPolicy ensures we always fetch from the server and skip // the local data cache. const {variables} props.appQueryRef; loadQuery(variables, {fetchPolicy: network-only}); }, [/* ... */]); return ( React.Suspense fallbackLoading query... MainContent refresh{refresh} queryRef{queryRef} / /React.Suspense ); }/** * MainContent.react.js */ // Renders the preloaded query, given the query reference function MainContent(props) { const {refresh, queryRef} props; const data usePreloadedQuery( graphql query AppQuery($id: ID!) { user(id: $id) { name friends { count } } } , queryRef, ); return ( h1{data.user?.name}/h1 divFriends count: {data.user.friends?.count}/div Button onClick{() refresh()} Fetch latest count /Button / ); }拆解这段代码背后的行为事件处理器中调用loadQuery我们在刷新的事件处理器即onClick里调用loadQuery网络请求会立即开始随后useQueryLoader内部会把更新后的queryRef写入 state组件重新渲染时把新的queryRef传给使用usePreloadedQuery的MainContent从而渲染出最新数据。fetchPolicy: network-only确保始终从网络获取、跳过本地数据缓存。Relay 默认的 fetch policy 是store-or-network即缓存有数据就用缓存因此刷新时若不显式覆盖可能拿不到服务器最新数据。会触发 Suspense调用loadQuery会重新渲染组件且由于network-only策略下必然发起网络请求usePreloadedQuery会进入挂起suspend状态具体机制见 Loading States with Suspense。因此必须用Suspense边界包裹MainContent以便展示 fallback 加载状态。源码视角useQueryLoader内部发生了什么从实现上看useQueryLoader把loadQuery的调用封装在一个useCallback中每次调用都会执行loadQuery(environment, preloadableRequest, variables, mergedOptions)并将返回的新PreloadedQuery通过setQueryReference写入 state见 useQueryLoader.js。这意味着每次调用loadQuery都会生成一个全新的、带新fetchKey的查询引用。在 loadQuery.js 的实现里每次调用loadQuery都会执行fetchKey目的是确保传给usePreloadedQuery的每个查询引用都被独立求值避免 Suspense 缓存直接复用上一次的结果而不是真正触发刷新。旧的查询引用会被妥善释放useQueryLoader用一个Set跟踪所有尚未释放的查询引用在新引用提交后、以及组件卸载时对旧引用调用releaseQuery()或对 live query 调用dispose()避免 Relay store 中的数据泄漏见 useQueryLoader.js。fetchPolicy会被原样透传给loadQuery。在loadQuery内部若显式传入了fetchPolicy则会跳过默认策略推导直接使用你提供的策略见 loadQuery.js只有未提供时才会根据请求类型推导默认值普通查询为store-or-networklive 查询为store-and-network纯客户端查询为store-only。如果你需要避免 Suspense在某些场景下你不希望展示 Suspense fallback——因为 fallback 会隐藏已经渲染出来的内容例如用户在浏览一份列表时刷新不应让整个列表闪回Loading。此时可以改用fetchQuery并手动维护一个加载状态注在未来支持并发渲染concurrent rendering的 React 版本中React 将提供选项来支持在挂起时不隐藏已渲染内容见 OssAvoidSuspenseNote.md。在当前版本下若想避免 fallback请使用下述方案。/** * App.react.js */ const AppQuery require(__generated__/AppQuery.graphql); function App(props: Props) { const environment useRelayEnvironment(); const [queryRef, loadQuery] useQueryLoader( AppQuery, props.appQueryRef /* initial query ref */ ); const [isRefreshing, setIsRefreshing] useState(false) const refresh useCallback(() { if (isRefreshing) { return; } const {variables} props.appQueryRef; setIsRefreshing(true); // fetchQuery will fetch the query and write // the data to the Relay store. This will ensure // that when we re-render, the data is already // cached and we dont suspend fetchQuery(environment, AppQuery, variables) .subscribe({ complete: () { setIsRefreshing(false); // *After* the query has been fetched, we call // loadQuery again to re-render with a new // queryRef. // At this point the data for the query should // be cached, so we use the store-only // fetchPolicy to avoid suspending. loadQuery(variables, {fetchPolicy: store-only}); } error: () { setIsRefreshing(false); } }); }, [/* ... */]); return ( React.Suspense fallbackLoading query... MainContent isRefreshing{isRefreshing} refresh{refresh} queryRef{queryRef} / /React.Suspense ); }拆解这段代码背后的行为自管理加载状态刷新时我们用isRefreshing状态标记刷新中避免进入 Suspense。可以在MainContent内部用这个状态渲染一个忙碌提示spinner 之类而不会隐藏MainContent本身。先fetchQuery后loadQuery在事件处理器中第一步调用fetchQuery发起网络请求并把响应数据写入本地 Relay store当fetchQuery的请求完成后再调用loadQuery获得一个更新后的queryRef传给usePreloadedQuery渲染最新数据——这一点与第一个示例的最终效果一致。store-only避免再次挂起当loadQuery被调用时查询数据应该已经缓存在本地 Relay store 中因此使用fetchPolicy: store-only——只读取已缓存的数据、不发起任何网络请求、不会导致 Suspense。为什么fetchQuerystore-only是可行的组合从源码看fetchQuery在 fetchQuery.js 中会把响应经过environment执行并写入 store因此订阅complete回调触发时查询数据已存在于本地缓存。它的默认fetchPolicy是network-only源码第 138 行即调用时必然发一次网络请求、拿到最新数据。而loadQuery在收到store-only策略时会直接跳过makeNetworkRequest只做environment.retain(operation)保留操作见 loadQuery.js。由于前一步fetchQuery已经把数据写进了 storeusePreloadedQuery再读取时无需等待网络自然也不会挂起。这正是避免 Suspense 刷新组合的底层原理。使用useLazyLoadQuery刷新查询在 Lazily Fetching Queries during Render 一节中我们介绍了useLazyLoadQueryHook在渲染期间懒加载查询。用它刷新查询的惯用做法是更新 state 中的选项借助fetchKey强制重新求值并重取/** * App.react.js */ const AppQuery require(__generated__/AppQuery.graphql); function App(props: Props) { const variables {id: 4}; const [refreshedQueryOptions, setRefreshedQueryOptions] useState(null); const refresh useCallback(() { // Trigger a re-render of useLazyLoadQuery with the same variables, // but an updated fetchKey and fetchPolicy. // The new fetchKey will ensure that the query is fully // re-evaluated and refetched. // The fetchPolicy ensures that we always fetch from the network // and skip the local data cache. setRefreshedQueryOptions(prev ({ fetchKey: (prev?.fetchKey ?? 0) 1, fetchPolicy: network-only, })); }, [/* ... */]); return ( React.Suspense fallbackLoading query... MainContent refresh{refresh} queryOptions{refreshedQueryOptions ?? {}} variables{variables} / /React.Suspense ); }/** * MainContent.react.js */ // Fetches and renders the query, given the fetch options function MainContent(props) { const {refresh, queryOptions, variables} props; const data useLazyLoadQuery( graphql query AppQuery($id: ID!) { user(id: $id) { name friends { count } } } , variables, queryOptions, ); return ( h1{data.user?.name}/h1 divFriends count: {data.user.friends?.count}/div Button onClick{() refresh()} Fetch latest count /Button / ); }拆解这段代码背后的行为更新 state 触发重新渲染在刷新事件处理器中更新组件的 state设置新的fetchKey与fetchPolicy使使用useLazyLoadQuery的MainContent以新的选项重新渲染并在渲染时重新获取查询。递增fetchKey每次更新都传入一个递增的fetchKey。给useLazyLoadQuery传入新的fetchKey会确保查询被完全重新求值并重新获取。fetchPolicy: network-only确保始终从网络获取、跳过本地数据缓存。会触发 Suspenserefresh中的 state 更新会使组件挂起见 Loading States with Suspense因为network-only策略下必然发起网络请求。因此同样需要用Suspense边界包裹MainContent以展示 fallback 加载状态。源码视角fetchKey与networkCacheConfig从 useLazyLoadQuery.js 的 Options 类型定义可以看到两个与本场景直接相关的选项fetchKey可以传入string | number。它用于在组件重新渲染时强制重新求值当前查询与变量即使变量没有变化、甚至组件没有重新挂载类似于给 React 组件传不同的key会使其重新挂载。如果fetchKey与上一次渲染时不同当前查询会被重新对照 store 求值并且根据当前fetchPolicy与缓存状态可能重新获取。在useLazyLoadQuery内部fetchKey会参与构造查询缓存标识符cacheBreaker ${forceUpdateKey}-${fetchKey ?? }见 useLazyLoadQueryNode.js这就是新 fetchKey 强制重新求值的机制来源。networkCacheConfig默认值为{force: true}这是传给网络层的缓存配置。注意网络层可能还有一层额外的查询响应缓存会复用相同查询的网络响应如果希望完全绕过这层缓存默认行为正是如此就传入{force: true}。useLazyLoadQuery在构造 operation 时会默认使用{force: true}作为该配置见 useLazyLoadQuery.js。另外注意loadQuery内部同样会把networkCacheConfig强制合并为force: true见 loadQuery.js所以两条刷新路径默认都会绕过网络层的响应缓存确保拿到真正最新的响应。如果你需要避免 Suspense与useQueryLoader一节相同若不想让 Suspense fallback 隐藏已渲染内容可以改用fetchQuery并自维护加载状态/** * App.react.js */ import type {AppQuery as AppQueryType} from AppQuery.graphql; const AppQuery require(__generated__/AppQuery.graphql); function App(props: Props) { const variables {id: 4} const environment useRelayEnvironment(); const [refreshedQueryOptions, setRefreshedQueryOptions] useState(null); const [isRefreshing, setIsRefreshing] useState(false) const refresh useCallback(() { if (isRefreshing) { return; } setIsRefreshing(true); // fetchQuery will fetch the query and write // the data to the Relay store. This will ensure // that when we re-render, the data is already // cached and we dont suspend fetchQuery(environment, AppQuery, variables) .subscribe({ complete: () { setIsRefreshing(false); // *After* the query has been fetched, we update // our state to re-render with the new fetchKey // and fetchPolicy. // At this point the data for the query should // be cached, so we use the store-only // fetchPolicy to avoid suspending. setRefreshedQueryOptions(prev ({ fetchKey: (prev?.fetchKey ?? 0) 1, fetchPolicy: store-only, })); } error: () { setIsRefreshing(false); } }); }, [/* ... */]); return ( React.Suspense fallbackLoading query... MainContent isRefreshing{isRefreshing} refresh{refresh} queryOptions{refreshedQueryOptions ?? {}} variables{variables} / /React.Suspense ); }拆解这段代码背后的行为自管理加载状态刷新时用isRefreshing标记状态在MainContent内部渲染忙碌提示不隐藏MainContent。先fetchQuery后更新 state事件处理器中先调用fetchQuery抓取数据并写入本地 Relay store请求完成后更新 state使组件以新的fetchKey与fetchPolicy重新渲染从而让useLazyLoadQuery渲染最新数据。store-only避免挂起更新 state 时数据已缓存因此用fetchPolicy: store-only只读取缓存避免挂起。四种方案速查与选型建议数据加载方式刷新手段是否触发 Suspense适用场景useQueryLoader/loadQuery再次调用loadQuery(variables, {fetchPolicy: network-only})是网络必然发生以 render-as-you-fetch 预加载查询、可接受 fallback 的场景useQueryLoaderfetchQueryfetchQuery写缓存后loadQuery(..., {fetchPolicy: store-only})否自维护isRefreshing不希望 fallback 隐藏已渲染内容列表、详情页刷新useLazyLoadQuery更新 state 中的fetchKey递增fetchPolicy: network-only是网络必然发生组件渲染期间懒加载查询、可接受 fallback 的场景useLazyLoadQueryfetchQueryfetchQuery写缓存后更新 state 的fetchKeyfetchPolicy: store-only否自维护isRefreshing懒加载查询 不希望 fallback 隐藏已渲染内容核心判断原则优先考虑实时能力如 GraphQL Subscriptions能从根本上省去手动刷新。优先采用 先fetchQuery写 store再以store-only读取 的组合它既能拿到最新数据又不会因 Suspense fallback 打断用户的阅读/操作。需要直接、简单地强制走网络时直接传fetchPolicy: network-only即可但要为 Suspense 准备好 fallback。fetchKey是useLazyLoadQuery场景下强制重新求值的关键开关务必在每次刷新时给出新值。关于fetchPolicy各取值的完整定义store-or-network/store-and-network/network-only/store-only可进一步参考 Fetch Policies 文档以及 useLazyLoadQuery.js 中对该选项逐条的中文注释说明。【免费下载链接】relayRelay is a JavaScript framework for building>项目地址: https://gitcode.com/gh_mirrors/relay29/relay创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考