后台重新获取与过期时间配置
为每个查询配置 staleTime 和 cacheTime，启用 refetchOnReconnect 以便设备恢复联网时同步数据，并实现网络状态提示条。
后台重新获取与过期时间配置 是 CoddyKit 上的免费 React Native Academy 课时。 这是第 4 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 React Native Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 React Native Academy 课程共包含 4 节课。
本课时的部分内容尚未翻译，以英文显示。
What Is Stale Data?
In React Query, data is considered stale when it is older than the configured staleTime. Stale data is not wrong — it's just potentially out of date. React Query displays stale data immediately from cache (no loading spinner) while scheduling a background refetch to get fresh data.
This stale-while-revalidate pattern is the key to why React Query feels so fast: users always see data immediately, and it silently updates in the background when needed. Understanding staleTime is essential to configuring this behavior correctly.
staleTime: How Long Data Is Fresh
staleTime is the number of milliseconds that cached data is considered fresh. During this window, React Query serves the cache without any network request — not even a background refetch. After staleTime expires, the data is still in the cache but considered stale, and a background refetch will happen next time it's needed.
The default staleTime is 0 — data is immediately stale after it's fetched! This means every component mount triggers a background refetch. Increasing staleTime dramatically reduces network traffic for data that doesn't change often.
// Default: staleTime = 0 (immediately stale)
const { data } = useQuery({
queryKey: ['user'],
queryFn: fetchUser,
// Every mount triggers a background refetch!
});
// Better: give fresh data a 5-minute window
const { data } = useQuery({
queryKey: ['user'],
queryFn: fetchUser,
staleTime: 5 * 60 * 1000, // 5 minutes
// No refetch for 5 minutes after last fetch
});Choosing the Right staleTime
The right staleTime depends on how often your data changes and how much users care about seeing the absolute latest version:
- User profile: 10-30 minutes (rarely changes)
- App configuration:
Infinity(changes only on deploy) - Social feed: 30 seconds to 2 minutes (new posts frequently)
- Live scores/prices: 0-10 seconds (must be current)
Set staleTime per-query to match the natural update frequency of each data type. One-size-fits-all staleTime leads to either too many requests or stale data in high-frequency contexts.
// Per-query staleTime based on data type:
const { data: profile } = useQuery({
queryKey: ['profile'],
queryFn: fetchProfile,
staleTime: 15 * 60 * 1000, // 15 min
});
const { data: feed } = useQuery({
queryKey: ['feed'],
queryFn: fetchFeed,
staleTime: 60 * 1000, // 1 min
});
const { data: config } = useQuery({
queryKey: ['config'],
queryFn: fetchConfig,
staleTime: Infinity, // never stale
});gcTime: How Long Cache Survives Without Observers
gcTime (garbage collection time) controls how long cached data stays in memory after all components observing it have unmounted. After this time the cache entry is deleted. New mounts for the same query then start fresh with a loading state.
gcTime defaults to 5 minutes. Set it higher for data you want available across navigation (e.g., the user navigates away and back). Set it lower for large data sets to save memory. gcTime must always be greater than or equal to staleTime — otherwise data could be garbage collected before it's even stale.
const queryClient = new QueryClient({
defaultOptions: {
queries: {
staleTime: 5 * 60 * 1000, // 5 min — no refetch window
gcTime: 30 * 60 * 1000, // 30 min — stay in memory
// gcTime >= staleTime is important!
},
},
});
// Per-query override:
const { data } = useQuery({
queryKey: ['large-dataset'],
queryFn: fetchLargeDataset,
gcTime: 60 * 1000, // free memory after 1 min offline
});refetchOnMount Behavior
refetchOnMount controls what happens when a component that uses a query mounts. The default value true means: if data is stale, trigger a background refetch. Set to false to never refetch on mount (only use the cache). Set to 'always' to always refetch even if data is still fresh.
For screens that must always show the latest data (like a payment confirmation screen), use refetchOnMount: 'always'. For screens that are fine with slightly stale data (like a settings screen), use false to avoid unnecessary network traffic.
// Always fresh on mount — for critical data:
const { data: accountBalance } = useQuery({
queryKey: ['balance'],
queryFn: fetchBalance,
refetchOnMount: 'always', // always refetch when screen opens
});
// Never refetch on mount — show cache only:
const { data: helpContent } = useQuery({
queryKey: ['help'],
queryFn: fetchHelp,
refetchOnMount: false,
staleTime: Infinity,
});refetchOnReconnect: Updating After Going Online
refetchOnReconnect triggers background refetches for all stale queries when the device regains network connectivity. This is the core of offline-first behavior — data automatically refreshes when the connection returns without any user action.
Enable this with the onlineManager and NetInfo integration (shown in the previous lesson). The default is true, but it only fires for stale queries. With staleTime: 0, all queries refetch on reconnect. With longer staleTimes, only queries that have expired refetch.
// Configure global:
const queryClient = new QueryClient({
defaultOptions: {
queries: {
refetchOnReconnect: true, // default — refetch stale on reconnect
staleTime: 2 * 60 * 1000, // data stale after 2 min
},
},
});
// Per-query override:
const { data } = useQuery({
queryKey: ['critical-data'],
queryFn: fetchCritical,
refetchOnReconnect: 'always', // always refetch on reconnect
});refetchInterval: Polling
refetchInterval turns a query into a polling query that automatically refetches at a fixed interval, even without user interaction. This is useful for real-time data like live scores, stock prices, or status dashboards.
Polling stops when the app is in the background or the device is offline. Use refetchIntervalInBackground: true to continue polling in the background. Be conservative with polling intervals — frequent polls drain battery and use data.
// Poll every 30 seconds:
const { data: serverStatus } = useQuery({
queryKey: ['server-status'],
queryFn: fetchServerStatus,
refetchInterval: 30 * 1000, // poll every 30s
refetchIntervalInBackground: false, // stop when app in background
});
// Poll only while user is watching (conditional):
const { data: liveScore } = useQuery({
queryKey: ['live-score', gameId],
queryFn: () => fetchScore(gameId),
refetchInterval: isGameLive ? 5000 : false, // poll only during live games
});Manual Refetch
Trigger a manual refetch using the refetch function returned by useQuery. This is useful for pull-to-refresh interactions where the user explicitly requests fresh data. The refetch function always fetches regardless of staleTime.
Combine with FlatList's onRefresh and refreshing props for standard pull-to-refresh UX. The isFetching flag from useQuery indicates when a refetch is in progress.
const { data, isFetching, refetch } = useQuery({
queryKey: ['posts'],
queryFn: fetchPosts,
});
return (
<FlatList
data={data}
renderItem={renderPost}
keyExtractor={(item) => item.id}
refreshing={isFetching}
onRefresh={refetch} // pull-to-refresh
/>
);Prefetching Queries
Prefetching loads data into the cache before the user navigates to the screen that needs it. Use queryClient.prefetchQuery to trigger a fetch and cache the result. When the user arrives at the screen, the query resolves instantly from the warm cache.
Prefetch in the navigation handler or when hovering a list item (on web) or when a list item approaches the viewport (onViewableItemsChanged in FlatList). The prefetched data has its own staleTime so it won't immediately expire.
const queryClient = useQueryClient();
async function handlePostPress(postId) {
// Prefetch before navigating:
await queryClient.prefetchQuery({
queryKey: ['post', postId],
queryFn: () => fetchPost(postId),
staleTime: 5 * 60 * 1000,
});
// Cache is now warm — navigate instantly:
navigation.navigate('PostDetail', { postId });
}Network Status Banner Pattern
Show users a network status banner when the device goes offline, and hide it when connectivity returns. Combine React Native's NetInfo with a context or Zustand store to broadcast network status to any component, and use React Query's background refetch to automatically sync when reconnected.
The banner should be subtle — an orange/red strip at the top or bottom indicating 'Offline mode — showing cached data'. Auto-dismiss it 2-3 seconds after the connection returns and a successful refetch completes.
import NetInfo from '@react-native-community/netinfo';
function useNetworkStatus() {
const [isOnline, setIsOnline] = React.useState(true);
React.useEffect(() => {
const unsubscribe = NetInfo.addEventListener((state) => {
setIsOnline(state.isConnected && state.isInternetReachable);
});
return unsubscribe;
}, []);
return isOnline;
}
// In root layout:
const isOnline = useNetworkStatus();
return (
<View style={{ flex: 1 }}>
{!isOnline && <OfflineBanner />}
<NavigationContainer>...</NavigationContainer>
</View>
);Coordinating staleTime with Server Cache Headers
If your API returns HTTP cache headers (like Cache-Control: max-age=300), align your React Query staleTime with the server's cache duration. This prevents the app from refetching data that the server wouldn't have updated yet anyway, saving bandwidth and server load.
For APIs without cache headers, set staleTime based on your knowledge of how frequently the data changes. Document your staleTime decisions in comments — they are architectural choices that affect user experience and server load in non-obvious ways.
// API returns Cache-Control: max-age=300 (5 minutes)
// Match staleTime to server cache duration:
const { data: articles } = useQuery({
queryKey: ['articles'],
queryFn: fetchArticles,
staleTime: 5 * 60 * 1000, // matches server max-age
// No point refetching — server would return same data
});
// Runtime staleTime from response header:
const staleTime = parseInt(response.headers.get('Cache-Control')
.match(/max-age=(\d+)/)?.[1] || '300') * 1000;Quick Check
Test your understanding of React Native Mobile Development concepts from this lesson.
Lesson Recap
In this lesson you learned: staleTime controls how long cached data is considered fresh before a background refetch is scheduled on next access, refetchOnReconnect: true automatically refreshes stale queries when network connectivity returns, and refetchInterval turns a query into a polling query that updates at a fixed interval — useful for live data. Congratulations on completing the Offline-First with React Query course — next you'll integrate Supabase as a full backend for your React Native app.
常见问题解答
「后台重新获取与过期时间配置」课时是免费的吗？
是的 — 「后台重新获取与过期时间配置」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 React Native Academy 课程的其余内容，请升级到 CoddyKit PRO。 React Native Academy 课程共包含 4 节课。
「后台重新获取与过期时间配置」这节课中我会学到什么？
为每个查询配置 staleTime 和 cacheTime，启用 refetchOnReconnect 以便设备恢复联网时同步数据，并实现网络状态提示条。 你通过在浏览器中直接运行的动手代码来练习 React Native Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 React Native Academy 需要有经验吗？
无需任何先前经验。CoddyKit 上的 React Native Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 4 节课，共 4 节。
「后台重新获取与过期时间配置」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 React Native Academy 课中编写并运行代码吗？
能。每节 React Native Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。
此课程中的所有课时
- QueryClient、QueryClientProvider 与 useQuery
- 使用 useMutation 执行变更与使缓存失效
- 使用 AsyncStorage 持久化查询缓存
- 后台重新获取与过期时间配置