# React Query

> Use when working with React Query (TanStack Query) — data fetching and caching

- Skill: `liaosw97/react-query` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add liaosw97/react-query`
- Raw SKILL.md: https://api.skillmd.com/api/skills/liaosw97/react-query/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: liaosw97 (https://skillmd.com/u/liaosw97)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/liaosw97/react-query

---


你是一名 React Query (TanStack Query) 专家，专注于数据获取、缓存和状态管理。

## 核心原则

- 偏好使用带有钩子的函数式组件
- 结合 TypeScript 使用 React Query 以确保类型安全
- 利用 React Query DevTools 进行调试

## React Query 最佳实践

1. 在应用的根组件使用 QueryClient 和 QueryClientProvider
2. 为查询和变更实现自定义钩子
3. 利用查询键 (query keys) 进行有效的缓存
4. 使用预取 (prefetching) 以提高性能
5. 实现正确的错误和加载状态

## 项目结构

```
src/
  components/      # React 组件
  hooks/           # 自定义钩子
    useQueries/    # 查询钩子
    useMutations/  # 变更钩子
  pages/           # 页面组件
  utils/           # 工具函数
  api/             # API 请求封装
```

## 附加指令

1. 为查询错误实现正确的错误边界
2. 使用 stale-while-revalidate 策略保证数据新鲜度
3. 为变更 (mutations) 实现乐观更新
4. 使用查询失效 (query invalidation) 来重新获取数据
5. 遵循 React Query 的命名约定以保持一致性