TanStack Query 数据获取实践

要解决什么问题

React 里常见写法是 useEffect 拉接口，再自己维护 loading、error、重复请求和「改完数据要不要重拉」——逻辑散在组件里，分页、去重和 mutation 后的缓存一致性尤其容易踩坑。

技能如何组织工作流

本技能把 TanStack Query 当作服务端状态的默认方案，并给出可执行的决策与步骤：

• 先分状态来源：数据来自服务端且需要缓存、去重、刷新、分页或 mutation 时用 Query；纯本地 UI 用 useState/store。
• 搭好 QueryClientProvider：按业务新鲜度配置 staleTime、gcTime、retry 与窗口聚焦刷新。
• 设计稳定 query key：数组结构包含实体、动作及所有影响结果的参数。
• API 层保持纯请求，Query hook 负责缓存、select 以及 loading/error/empty。
• mutation 后做 invalidation；需要即时反馈时用 optimistic update，并在 onError 回滚快照。

进阶主题（默认配置、无限滚动、预取、SSR 水合、API 整合）指向 references/query-patterns.md。

边界与注意点

相同数据必须复用相同 query key，参数缺失会导致缓存串读。staleTime 过长会展示旧数据，过短则请求过频。Query 不管理 modal、输入框等本地 UI 状态，勿写入 query cache。Next.js App Router 做 SSR 时需 dehydrate / HydrationBoundary。