useQuery useQuery 查询
最后更新：2026-10-28
useQuery useQuery 查询
TanStack Query 的 useQuery 管理整个「请求生命周期 + 缓存」：自动去重、后台刷新，staleTime 控制数据多久算新鲜，invalidateQueries 失效重取。组件只声明「我需要什么数据」，其余交给库。
| 分组 | 数据与工程化 |
|---|---|
| 类型 | Hook |
| 引入版本 | TanStack Query v5 |
ℹ️ 说明 编辑器将 JSX 转译为 JavaScript 后在沙箱中渲染真实界面；组件自动挂载，无需手写 render 调用。
📝 语法
import { useQuery } from '@tanstack/react-query'
const { data, isPending, isError, error, refetch } = useQuery({
queryKey: ['todo', id], // 缓存键：变化即切换/重新查询
queryFn: () => fetch('/api/todos/' + id).then(r => r.json()),
staleTime: 30_000 // 30 秒内数据新鲜，不重新请求
})
// isPending：无缓存首次加载；isFetching：任何后台刷新中⚙️ 参数
| queryKey | 缓存键（数组）：['todos', id] 中 id 变化会切到对应缓存并重新请求；键相同则复用缓存。 |
|---|---|
| staleTime | 数据保鲜期（毫秒）：期内重挂载直接用缓存；过期后重挂载会后台静默刷新（stale-while-revalidate）。 |
返回值：返回 { data, isPending, isError, error, refetch, isFetching } 等查询状态：data 为最新数据，refetch 手动失效重取。
▶ 示例
示例可直接运行：展开后自动渲染，编辑代码即时生效。
输出结果：
第一次读取等 0.8 秒；之后点「读取」秒出（命中 Map 缓存）；点「refetch」强制重新请求并更新缓存——staleTime 与失效的核心思想（模拟演示）。💡 要点
💡 提示 queryKey 里放全部依赖（['todos', filter, page]），库会自动在依赖变化时重查——等于把 useEffect 依赖数组交给了缓存层。
⚠️ 注意 queryKey 必须包含全部请求参数且可序列化；漏了参数会导致不同数据共用同一缓存键，出现「张冠李戴」。
ℹ️ 说明 v5 把 loading 改名 isPending：isPending 表示无缓存首载，isFetching 表示含后台刷新，两者含义不同。
🏷️ 数据与工程化相关
💡 相关案例
更多案例整理中，敬请期待。
📚 相关教程
❓ 常见问题
Q staleTime 和 gcTime（原 cacheTime）什么区别？
A staleTime 管「多久内数据算新鲜、不用重查」；gcTime 管缓存「多久没人用就回收」。前者影响请求频率，后者影响内存。
Q 数据变了怎么让它刷新？
A 调 refetch()，或用 queryClient.invalidateQueries({ queryKey }) 把相关查询标记失效，命中的组件自动后台重取。
Q 为什么要用数组做 queryKey 而不是字符串？
A 数组是结构化键：['todos', 2] 与 ['todos', 3] 精确区分；还能整体失效 ['todos'] 前缀下所有查询，层级化管理缓存。
