本文介绍在 react query 中实现“按需且智能”的数据刷新策略：仅当缓存数据已过期（stale）时才发起网络请求，避免无效调用；重点讲解懒加载查询（lazy queries）与动态 querykey 的配合使用。
在 React Query 中，refetch() 默认会无视缓存状态，强制发起新请求——这与 useQuery 初始化时的“仅 stale 时自动拉取”行为不一致。若你希望在用户交互（如点击、输入）中复现同样的“智能刷新”逻辑（即：有缓存且未过期则直接返回，过期才发请求），不应手动调用 refetch()，而应让 Query 实例自然响应其自身的 staleness 状态。
最符合该需求的模式是 Lazy Query（懒加载查询）：通过控制 enabled 选项动态启停查询，并将触发条件（如搜索关键词）纳入 queryKey。React Query 会自动基于 queryKey 唯一性管理缓存，并在 key 变更且对应数据 stale 时自动触发请求。
以下是一个典型搜索场景的实现：
import { useQuery } from '@tanstack/react-query';
function SearchResults() {
const [searchTerm, setSearchTerm] = useState('');
const { data, isLoading, error } = useQuery({
queryKey: ['search', searchTerm], // ✅ key 包含动态参数，确保不同搜索词独立缓存
queryFn: () => fetchSearchResults(searchTerm),
enabled: searchTerm.length > 0, // ✅ 仅当有有效输入时启用查询（懒加载）
staleTime: 30_000, // 可选：设置 30 秒内视为 fresh，避免频繁重复请求
});
return (
<div>
<input
value={searchTerm}
onChange={(e) => setSearchTerm(e.target.value)}
placeholder="Enter search term..."
/>
{isLoading && <p>Loading...</p>}
{error && <p>Error: {(error as Error).message}</p>}
{data && <ul>{data.map(item => <li key={item.id}>{item.title}</li>)}</ul>}
</div>
);
}✅ 关键要点说明：
- queryKey 必须包含所有影响结果的变量（如 searchTerm），否则 React Query 无法区分不同请求，导致缓存错乱或跳过必要请求；
- enabled: !!searchTerm 是懒加载核心：初始为 false，不发起请求；输入后变为 true，Query 自动进入“active”状态，并根据当前缓存是否 stale 决定是否 fetch；
- 无需手动 refetch()：每次 searchTerm 变化 → queryKey 变化 → React Query 自动匹配缓存并判断 staleness → 仅 stale 时调用 queryFn；
- 如需进一步控制 freshness，可配置 staleTime（默认 0，即始终 stale）、cacheTime 或 refetchOnMount 等选项。
⚠️ 注意事项：
- 避免在 queryFn 中闭包捕获外部变量（如 searchTerm），务必通过 queryKey 传参并在 queryFn 中解构使用（或直接作为参数传入），确保依赖显式、可追踪；
- 若需在非 key 变更场景下“主动刷新当前查询”，可结合 queryClient.invalidateQueries({ queryKey: ['search', searchTerm] }) + refetchOnReconnect: false 等策略，但通常懒加载 + key 驱动已覆盖绝大多数交互场景。
总结：React Query 的“智能刷新”本质依赖于 queryKey 的语义化设计 和 enabled 的精准控制。放弃对 refetch() 的路径依赖，转而让数据流由 key 和状态驱动，才能真正实现既高效又符合直觉的数据同步体验。
