用途
该技能面向在现代 React 应用（尤其是 Next.js App Router 与 Server Components）中使用 @tanstack/react-query 的开发者，提供专家级实践模式。它适用于配置 QueryClient、实现 mutations、调试性能问题，以及添加乐观更新等场景。
主要能力
技能内容以“禁止事项”清单为核心，强调若干关键约束：
- 禁止在服务端使用单例 QueryClient，以避免用户间数据泄漏与竞态条件，每个请求必须获得独立的 QueryClient 实例。
- 禁止将查询数据同步到 useState，因为后台重新获取、失效与乐观更新都会修改缓存，本地状态副本会立即过期。
- 禁止在列表项组件内部放置查询，否则 N 个条目会产生 N 个观察者，每次缓存更新都触发 O(n) 遍历。
- 禁止使用不稳定的查询键（如非保证顺序的数组、Date.now()、无确定性序列化的对象键）。
- 禁止跳过依赖查询的 enabled 守卫。
- 禁止忽略 AbortController 信号。
- 禁止对高风险或外部变更使用乐观更新。
- 禁止假设结构共享没有成本（对超过 1000 条且频繁更新的数据集，应设置 structuralSharing: false）。
- 禁止在乐观更新中跳过 onSettled。
- 禁止假设缓存失效是同步的。
- 禁止在不做结构比较的情况下使用 setQueryData。
- 禁止忘记处理水合不匹配。
技能还提供使用前的自问清单，涵盖状态分类（服务端状态 vs 客户端状态）、缓存策略（数据新鲜度、查询生命周期）、观察者经济学（多少组件订阅同一查询、是 N 个查询还是 1 个查询带 N 个观察者）。
使用方式
技能采用渐进式披露以最小化上下文占用，按场景加载参考文件：
- 场景 1：设置 Query Client。必须完整阅读 query-client-setup.md（约 125 行）与 server-integration.md（约 151 行），并复制 assets/query-client.ts 以获得生产就绪配置。
- 场景 2：构建查询钩子。必须阅读 query-keys.md（约 151 行）；若使用服务端组件则阅读 server-integration.md；除非实现变更，否则不加载 mutations-and-updates.md。
- 场景 3：实现变更。必须完整阅读 mutations-and-updates.md（约 345 行），并参考 patterns-and-pitfalls.md 了解回滚模式。
- 场景 4：调试性能问题。先检查观察者数量阈值表；若观察者数量 >50 则阅读 patterns-and-pitfalls.md；若涉及大数据集问题则阅读 fundamentals.md。
- 场景 5：多层缓存策略。必须阅读 caching-strategy.md（约 198 行），用于统一的 Next.js use cache + TanStack Query + HTTP 缓存模式。
技能还提供查询配置决策矩阵（按数据类型给出 staleTime、gcTime、refetchInterval、structuralSharing 建议）、变更模式选择表（表单提交、切换、拖拽、批量操作、生命攸关操作、审计追踪等场景对应悲观或乐观模式）、查询键架构（分层工厂与失效示例）、服务端-客户端集成模式（Next.js use cache、TanStack Query、浏览器 HTTP 缓存三层及其失效方法）、观察者数量阈值表、查询钩子模式表、常见错误模式与修复表、排查决策树（性能问题、网络问题、水合问题）以及自由度校准表。
适用场景
- 在 Next.js App Router 中配置 QueryClient 与服务端/客户端集成。
- 设计稳定的查询键与分层失效架构。
- 实现乐观或悲观变更，并处理回滚与清理。
- 诊断重复请求、无限请求、列表渲染缓慢、缓存不清理、水合不匹配等性能与正确性问题。
- 设计 Next.js use cache、TanStack Query 与 HTTP 缓存的多层统一失效策略。
限制
资料未提供该技能的安装命令、收费方式、支持平台或具体版本要求。部分参考文件（如 query-client-setup.md、server-integration.md、query-keys.md、mutations-and-updates.md、patterns-and-pitfalls.md、fundamentals.md、caching-strategy.md）的具体内容未在资料中完整给出，仅提供了行数估计与用途说明。