@qiaopeng/tanstack-query-plus 完整使用教程

> 本教程将带你从零开始，循序渐进地学习如何使用 @qiaopeng/tanstack-query-plus。每个章节都会自然地引出下一个概念，帮助你建立完整的知识体系。

目录

1. 前言：为什么需要这个库？
2. 安装与环境准备
3. 第一步：配置 Provider
4. 第二步：发起你的第一个查询
5. 第三步：使用增强查询追踪性能
6. 第四步：管理 Query Key
7. 第五步：数据变更与乐观更新
8. 第六步：无限滚动与分页
9. 第七步：全局状态与 Mutation 监控
10. 第八步：批量查询与仪表盘
11. 第九步：智能预取
12. 第十步：Suspense 模式与 SSR
13. 第十一步：离线支持与持久化
14. 第十二步：数据防护与安全
15. 第十三步：焦点管理
16. 第十四步：工具函数与选择器
17. 最佳实践与常见问题
18. API 索引

---

1. 前言：为什么需要这个库？

在使用 TanStack Query（原 React Query）时，你可能会遇到以下问题：

- 配置繁琐：每次新项目都要重新配置 staleTime、gcTime、重试策略等
- 缺乏最佳实践：不确定什么样的配置才是最优的
- 重复代码：乐观更新、错误处理、性能追踪等逻辑需要反复编写
- 离线支持复杂：实现离线队列和数据持久化需要大量代码

@qiaopeng/tanstack-query-plus 就是为了解决这些问题而生的。它在 TanStack Query v5 的基础上，提供了：

- 🚀 开箱即用的最佳实践配置
- 🔄 增强的 Hooks（性能追踪、慢查询检测、错误日志）
- 💾 一键启用的持久化
- 📡 完整的离线支持
- ⚡ 多种智能预取策略
- 🎯 内置乐观更新

接下来，让我们一步步学习如何使用这些功能。

$3

- 保持与 TanStack Query v5 完全兼容，不改变其核心行为，只做“安全增强”。
- 提供开箱即用的最佳实践配置，减少重复劳动与认知负担。
- 以“安全”为首要前提：数据防护、持久化安全、离线队列的稳健性、错误处理的可控性。
- API 设计坚持渐进增强：原生用法不变，增强能力按需启用，便于迁移和学习。
- TypeScript 友好：导出类型与范型参数与 TanStack 保持一致，避免类型陷阱。

$3

- 中大型前端应用，需要统一的查询管理与最佳实践配置。
- 有离线需求（电商、文档编辑、移动端 Web）或需要缓存持久化与恢复的场景。
- 需要更强的乐观更新、并发冲突处理、数据一致性保障。
- 希望最小化自定义基础设施代码，将精力聚焦在业务逻辑。

$3

- 不替代后端的并发控制与数据一致性保障；前端 Data Guard 仅作为“最后防线”。
- 不内置与具体后端协议的强绑定（如 GraphQL/REST 的特定实现）；保持通用。
- 不存储任何敏感凭据；持久化仅针对查询缓存，且可配置与可关闭。

$3

- 持久化默认仅保存可序列化且成功的查询数据，避免异常对象导致恢复失败（参见 createPersistOptions）。
- 建议不要在 queryKey 中包含敏感信息（如 token、身份证号、手机号原文）。
- DevTools 仅在开发环境启用，避免在生产泄露内部状态（参见 isDevToolsEnabled）。
- 离线队列持久化时去除了函数体，仅存操作元数据；实际执行函数需通过注册表安全绑定。

$3

- queryKey：查询的唯一标识；必须是稳定、可序列化的值（通常为数组）
- queryFn：实际获取数据的异步函数；返回 Promise
- staleTime：数据保持“新鲜”的时间窗口；新鲜期内不会重复请求
- gcTime：缓存保留时间；超过后缓存会被清理
- invalidate：标记查询为过期；下一次渲染或焦点恢复时会重新请求
- refetch：主动重新请求数据
- persist：将查询缓存持久化到存储（localStorage/IndexedDB）并在刷新后恢复
- offline：网络不可用时的状态；本库提供队列与自动恢复机制
- optimistic update：先更新 UI，再与服务端同步；失败时需回滚
- Data Guard：防止旧数据覆盖新数据的前端机制（版本/时间戳/哈希比对）
---

2. 安装与环境准备

$3

首先，安装必需的包：

``bash
npm install @qiaopeng/tanstack-query-plus @tanstack/react-query @tanstack/react-query-persist-client
`

这三个包的作用分别是：
- @qiaopeng/tanstack-query-plus：本库，提供增强功能
- @tanstack/react-query：TanStack Query 核心库
- @tanstack/react-query-persist-client：持久化支持

$3

根据你的需求，可以选择安装以下可选依赖：

`bash


开发调试工具（强烈推荐在开发环境使用）

1. 安装依赖：确保安装本库及 peer 依赖（@tanstack/react-query、react、react-dom），按需安装 devtools、react-intersection-observer、react-router-dom
2. 创建 QueryClient：使用 GLOBAL_QUERY_CONFIG，避免随意调整 retry、staleTime 造成请求风暴
3. 包裹应用：使用 PersistQueryClientProvider 开启持久化与离线支持（生产环境建议保留持久化）
4. 添加 DevTools（开发环境）：isDevToolsEnabled() 控制显示，严禁在生产强制开启
5. 发起首个查询：优先使用 useEnhancedQuery，在慢查询或错误场景验证日志输出
6. 增强 Mutation：在列表 CRUD 场景启用乐观更新，并验证回滚路径与错误处理
7. 离线与持久化：断网测试页面行为；验证缓存恢复与离线队列的稳健性
8. 数据防护（可选但推荐）：开启 Data Guard 的版本/时间戳/哈希策略，防止旧数据覆盖
9. 焦点管理：按照业务需要控制窗口聚焦时的刷新频率，避免抖动
10. 预取：根据网络情况与页面流量，按需启用悬停/视口/路由/空闲预取，避免过度预取

完成以上 10 点后，再进入“最佳实践与常见问题”章节进行整体检查与性能、安全优化。

$3

目标：用 5 分钟完成“配置 Provider + 首个查询 + DevTools 调试”。

1. 安装依赖：

`bash
npm install @qiaopeng/tanstack-query-plus @tanstack/react-query @tanstack/react-query-persist-client
npm install @tanstack/react-query-devtools --save-dev
`

2. 创建 Provider：

`tsx
// main.tsx
import { QueryClient, PersistQueryClientProvider } from '@qiaopeng/tanstack-query-plus'
import { GLOBAL_QUERY_CONFIG } from '@qiaopeng/tanstack-query-plus/core'
import { ReactQueryDevtools, isDevToolsEnabled } from '@qiaopeng/tanstack-query-plus/core/devtools'

const queryClient = new QueryClient({ defaultOptions: GLOBAL_QUERY_CONFIG })

function Providers({ children }) {
return (

{children}
{isDevToolsEnabled() && }

)
}
`

3. 发起首个查询：

`tsx
// App.tsx
import { useEnhancedQuery } from '@qiaopeng/tanstack-query-plus/hooks'

export default function App() {
const { data, isLoading, isError } = useEnhancedQuery({
queryKey: ['hello'],
queryFn: async () => ({ message: 'Hello Query Plus' }),
})
if (isLoading) return

4. 跑起来：在浏览器中打开 DevTools 面板，查看 ['hello'] 查询状态。

$3

以下 tsconfig.json 选项可以帮助初学者避免常见类型问题：

`json
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"moduleResolution": "Node",
"jsx": "react-jsx",
"strict": true,
"skipLibCheck": true,
"esModuleInterop": true,
"forceConsistentCasingInFileNames": true,
"resolveJsonModule": true,
"isolatedModules": true,
"useUnknownInCatchVariables": true
}
}
`

说明：
- strict: true 有助于暴露隐含的 any 与未处理的 undefined
- skipLibCheck: true 可避免第三方库类型检查的噪音（对本库安全）
- useUnknownInCatchVariables 提醒你显式处理错误类型

---

3. 第一步：配置 Provider

任何使用 TanStack Query 的应用都需要一个 Provider 来提供 QueryClient 实例。本库提供了一个增强版的 Provider，让配置变得更简单。

$3

最简单的配置只需要几行代码：

`tsx
// App.tsx
import { QueryClient, PersistQueryClientProvider } from '@qiaopeng/tanstack-query-plus'
import { GLOBAL_QUERY_CONFIG } from '@qiaopeng/tanstack-query-plus/core'

// 创建 QueryClient，使用预配置的最佳实践
const queryClient = new QueryClient({
defaultOptions: GLOBAL_QUERY_CONFIG
})

function App() {
return (



)
}
`

这段代码做了什么？

1. 创建 QueryClient：使用 GLOBAL_QUERY_CONFIG 预配置，包含了经过优化的默认值
2. 包裹应用：PersistQueryClientProvider 让所有子组件都能访问 QueryClient

$3

PersistQueryClientProvider 默认就启用了持久化和离线支持（enablePersistence 和 enableOfflineSupport 默认都是 true）。如果你想显式配置或禁用某些功能：

`tsx
client={queryClient}
enablePersistence={true} // 启用 localStorage 持久化（默认 true）
enableOfflineSupport={true} // 启用离线状态监听（默认 true）
cacheKey="my-app-cache" // 自定义缓存 key（默认 'tanstack-query-cache'）
onPersistRestore={() => console.log('缓存已恢复')} // 缓存恢复回调
onPersistError={(err) => console.error('持久化错误', err)}
>


`

enablePersistence 的作用：
- 自动将查询缓存保存到 localStorage
- 页面刷新后自动恢复缓存数据
- 用户可以立即看到上次的数据，无需等待网络请求
- 设为 false 可禁用持久化

enableOfflineSupport 的作用：
- 监听网络状态变化
- 离线时暂停请求，在线时自动恢复
- 配合离线队列管理器使用
- 设为 false 可禁用离线支持

$3

GLOBAL_QUERY_CONFIG 包含了以下默认值：

`typescript
{
queries: {
staleTime: 30000,
gcTime: 600000,
retry: defaultQueryRetryStrategy, // 智能重试：4XX不重试，5XX最多1次
retryDelay: exponentialBackoff,
refetchOnWindowFocus: true,
refetchOnReconnect: true,
refetchOnMount: true,
},
mutations: {
retry: 0, // Mutation 默认不重试
retryDelay: exponentialBackoff,
gcTime: 600000,
}
}
`

重试策略说明：

- Query 重试（defaultQueryRetryStrategy）：
- 4XX 客户端错误：不重试（客户端问题，重试无意义）
- 5XX 服务端错误：最多重试 1 次（避免过度重试）
- 网络错误：最多重试 2 次

- Mutation 重试（defaultMutationRetryStrategy）：
- 4XX 客户端错误：不重试
- 5XX 服务端错误：不重试（避免重复操作）
- 网络错误：最多重试 1 次

这些值是经过实践验证的最佳实践，适合大多数应用场景。

$3

本库还提供了针对不同环境的预配置：

`tsx
import { getConfigByEnvironment } from '@qiaopeng/tanstack-query-plus/core'

// 根据环境自动选择配置
const env =
process.env.NODE_ENV === 'production'
? 'production'
: process.env.NODE_ENV === 'test'
? 'test'
: 'development'
const config = getConfigByEnvironment(env)
const queryClient = new QueryClient({ defaultOptions: config })
`

不同环境的配置差异：

| 配置项 | development | production | test |
|--------|-------------|------------|------|
| staleTime | 0 | 10 分钟 | 0 |
| retry (Query) | 智能重试 | 智能重试 | 0 |
| retry (Mutation) | 0 | 0 | 0 |
| refetchOnWindowFocus | true | true | false |

*智能重试：4XX 不重试，5XX 最多 1 次，网络错误最多 2 次

补充：还支持 getConfigByEnvironment('longCache') 与 getConfigByEnvironment('realtime') 两种预设，分别适用于“长缓存”与“高实时”场景。

$3

如果默认的重试策略不满足你的需求，可以使用 createSafeRetryStrategy 和 createErrorSafeConfig 来自定义：

`tsx
import {
createSafeRetryStrategy,
createErrorSafeConfig
} from '@qiaopeng/tanstack-query-plus/core'

// 方式一：创建自定义重试策略
const customRetry = createSafeRetryStrategy(
0, // 4XX 错误重试次数
1, // 5XX 错误重试次数
2 // 其他错误重试次数
)

const queryClient = new QueryClient({
defaultOptions: {
queries: {
retry: customRetry,
}
}
})

// 方式二：使用错误安全配置（推荐）
const errorSafeConfig = createErrorSafeConfig({
maxRetries4xx: 0, // 4XX 不重试
maxRetries5xx: 0, // 5XX 不重试（严格模式）
maxRetriesOther: 1, // 网络错误最多 1 次
disableFocus: false, // 是否禁用窗口聚焦时 refetch
disableReconnect: false // 是否禁用重连时 refetch
})

const queryClient = new QueryClient({
defaultOptions: errorSafeConfig
})
`

使用场景：

1. 严格模式：完全禁用 4XX/5XX 重试，避免不必要的请求
2. 宽松模式：增加重试次数，适合网络不稳定的环境
3. 自定义场景：根据业务需求精确控制重试行为

$3

在开发环境中，强烈建议添加 DevTools 来调试查询状态：

`tsx
import { ReactQueryDevtools, isDevToolsEnabled } from '@qiaopeng/tanstack-query-plus/core/devtools'

function App() {
return (


{isDevToolsEnabled() && }

)
}
`

DevTools 可以让你：
- 查看所有查询的状态
- 手动触发 refetch
- 查看缓存数据
- 调试查询问题

现在 Provider 配置好了，让我们开始发起第一个查询！

---

4. 第二步：发起你的第一个查询

配置好 Provider 后，我们就可以在组件中使用查询了。

$3

最基本的查询可以使用 TanStack Query 原生的 useQuery，或者本库提供的增强版 useEnhancedQuery：

`tsx
// 方式一：使用 TanStack Query 原生 useQuery
import { useQuery } from '@tanstack/react-query'

// 方式二：使用本库的增强版（推荐，支持性能追踪等功能）
import { useEnhancedQuery } from '@qiaopeng/tanstack-query-plus/hooks'

function UserProfile({ userId }) {
// 两者用法相同，useEnhancedQuery 额外支持性能追踪
const { data, isLoading, isError, error } = useEnhancedQuery({
queryKey: ['user', userId], // 查询的唯一标识
queryFn: () => fetch(/api/users/${userId}).then(r => r.json()), // 获取数据的函数
})

if (isLoading) return

3. 返回值：
- data：查询成功后的数据
- isLoading：首次加载中
- isError：是否出错
- error：错误对象

$3

有时候我们需要在满足某些条件时才发起查询：

`tsx
import { useEnhancedQuery } from '@qiaopeng/tanstack-query-plus/hooks'

function UserProfile({ userId }) {
const { data } = useEnhancedQuery({
queryKey: ['user', userId],
queryFn: () => fetchUser(userId),
enabled: !!userId, // 只有 userId 存在时才查询
})

// ...
}
`

$3

另一种禁用查询的方式是使用 skipToken：

`tsx
import { useEnhancedQuery, skipToken } from '@qiaopeng/tanstack-query-plus/hooks'

function UserProfile({ userId }) {
const { data } = useEnhancedQuery({
queryKey: ['user', userId],
queryFn: userId ? () => fetchUser(userId) : skipToken,
})

// ...
}
`

注意：skipToken 也可以从 @qiaopeng/tanstack-query-plus 主包导入，或者从 @tanstack/react-query 导入。

skipToken 的好处是 TypeScript 类型推断更准确。

$3

你可以为特定查询设置不同的缓存策略：

`tsx
import { useEnhancedQuery } from '@qiaopeng/tanstack-query-plus/hooks'

const { data } = useEnhancedQuery({
queryKey: ['user', userId],
queryFn: () => fetchUser(userId),
staleTime: 5 60 1000, // 5 分钟内数据视为新鲜
gcTime: 30 60 1000, // 缓存保留 30 分钟
})
`

staleTime vs gcTime 的区别：

- staleTime：数据被认为是"新鲜"的时间。在这段时间内，即使组件重新挂载，也不会重新请求。
- gcTime：数据在缓存中保留的时间。超过这个时间，数据会被垃圾回收。

现在你已经会发起基本查询了。但在实际项目中，我们往往需要追踪查询性能、检测慢查询。这就是增强查询的用武之地。

---

5. 第三步：使用增强查询追踪性能


useEnhancedQuery 是本库的核心 Hook 之一，它在原生 useQuery 的基础上增加了性能追踪、慢查询检测和错误日志功能。

$3

`tsx
import { useEnhancedQuery } from '@qiaopeng/tanstack-query-plus/hooks'

function UserProfile({ userId }) {
const {
data,
isLoading,
isError,
error,
// 增强的返回值
refetchCount, // 重新获取次数
lastQueryDuration // 最后一次查询耗时（毫秒）
} = useEnhancedQuery({
queryKey: ['user', userId],
queryFn: () => fetchUser(userId),
})

if (isLoading) return

要追踪查询性能，需要显式启用 trackPerformance：

`tsx
const { data, lastQueryDuration } = useEnhancedQuery({
queryKey: ['user', userId],
queryFn: () => fetchUser(userId),
trackPerformance: true, // 启用性能追踪
})
`

启用后，lastQueryDuration 会记录每次查询的耗时。

$3

在生产环境中，检测慢查询对于性能优化至关重要：

`tsx
const { data } = useEnhancedQuery({
queryKey: ['user', userId],
queryFn: () => fetchUser(userId),
trackPerformance: true,
slowQueryThreshold: 2000, // 超过 2 秒视为慢查询
onSlowQuery: (duration, queryKey) => {
// 上报到监控系统
analytics.track('slow_query', {
queryKey: JSON.stringify(queryKey),
duration,
})
console.warn(慢查询警告: ${JSON.stringify(queryKey)} 耗时 ${duration}ms)
},
})
`

实际应用场景：

1. 性能监控：将慢查询上报到 APM 系统（如 Sentry、DataDog）
2. 开发调试：在开发环境中快速发现性能问题
3. 用户体验优化：识别需要优化的 API 接口

$3

useEnhancedQuery 默认在开发环境自动记录错误：

`tsx
const { data } = useEnhancedQuery({
queryKey: ['user', userId],
queryFn: () => fetchUser(userId),
logErrors: true, // 默认在开发环境为 true
})
`

当查询出错时，控制台会输出：
`
[useEnhancedQuery Error] ["user","123"]: Error: Network request failed
`

如果你想在生产环境禁用错误日志：

`tsx
logErrors: process.env.NODE_ENV === 'development'
`

$3

`tsx
import { useEnhancedQuery } from '@qiaopeng/tanstack-query-plus/hooks'

function UserDetailPage({ userId }) {
const {
data: user,
isLoading,
isError,
error,
refetchCount,
lastQueryDuration,
refetch
} = useEnhancedQuery({
queryKey: ['user', userId],
queryFn: async () => {
const response = await fetch(/api/users/${userId})
if (!response.ok) throw new Error('获取用户失败')
return response.json()
},
trackPerformance: true,
slowQueryThreshold: 3000,
onSlowQuery: (duration, queryKey) => {
// 发送到监控系统
reportSlowQuery({ queryKey, duration })
},
})

if (isLoading) {
return
}

if (isError) {
return (
message={error.message}
onRetry={() => refetch()}
/>
)
}

return (


现在你已经掌握了增强查询的使用。但你可能注意到，我们一直在手写 queryKey，比如 ['user', userId]。随着项目变大，管理这些 key 会变得困难。接下来，让我们学习如何优雅地管理 Query Key。

---

6. 第四步：管理 Query Key

Query Key 是 TanStack Query 的核心概念。好的 Key 管理策略可以让你的代码更易维护、更不容易出错。

$3

考虑以下场景：

`tsx
// 组件 A
useQuery({ queryKey: ['user', userId], ... })

// 组件 B
useQuery({ queryKey: ['users', userId], ... }) // 拼写错误！

// 组件 C - 需要失效用户缓存
queryClient.invalidateQueries({ queryKey: ['user', userId] })
`

问题：
1. 拼写错误导致缓存不共享
2. 修改 key 结构时需要全局搜索替换
3. 没有类型提示

$3

本库提供了一套预定义的 Key 工厂：

`tsx
import { queryKeys } from '@qiaopeng/tanstack-query-plus/core'

// 用户相关
queryKeys.users() // ['tanstack-query', 'users']
queryKeys.user('123') // ['tanstack-query', 'users', '123']
queryKeys.userProfile('123') // ['tanstack-query', 'users', '123', 'profile']
queryKeys.userSettings('123') // ['tanstack-query', 'users', '123', 'settings']
queryKeys.usersByRole('admin') // ['tanstack-query', 'users', 'by-role', 'admin']

// 文章相关
queryKeys.posts() // ['tanstack-query', 'posts']
queryKeys.post('456') // ['tanstack-query', 'posts', '456']
queryKeys.postsByUser('123') // ['tanstack-query', 'posts', 'by-user', '123']
queryKeys.postComments('456') // ['tanstack-query', 'posts', '456', 'comments']

// 搜索
queryKeys.search('react', 'posts') // ['tanstack-query', 'search', { query: 'react', type: 'posts' }]

// 通知
queryKeys.notifications() // ['tanstack-query', 'notifications']
queryKeys.unreadNotifications() // ['tanstack-query', 'notifications', 'unread']
`

使用示例：

`tsx
import { queryKeys } from '@qiaopeng/tanstack-query-plus/core'
import { useEnhancedQuery } from '@qiaopeng/tanstack-query-plus/hooks'

function UserProfile({ userId }) {
const { data } = useEnhancedQuery({
queryKey: queryKeys.user(userId), // 类型安全，不会拼错
queryFn: () => fetchUser(userId),
})

// ...
}

// 失效缓存时也使用同样的 key
function useUpdateUser() {
const queryClient = useQueryClient()

return useMutation({
mutationFn: updateUser,
onSuccess: (_, { userId }) => {
// 失效该用户的所有相关缓存
queryClient.invalidateQueries({ queryKey: queryKeys.user(userId) })
}
})
}
`

$3

对于内置 Key 工厂没有覆盖的业务领域，可以创建自定义工厂：

`tsx
import { createDomainKeyFactory } from '@qiaopeng/tanstack-query-plus/core'

// 创建产品域的 Key 工厂
const productKeys = createDomainKeyFactory('products')

productKeys.all() // ['tanstack-query', 'products']
productKeys.lists() // ['tanstack-query', 'products', 'list']
productKeys.list({ page: 1 }) // ['tanstack-query', 'products', 'list', { page: 1 }]
productKeys.details() // ['tanstack-query', 'products', 'detail']
productKeys.detail('abc') // ['tanstack-query', 'products', 'detail', 'abc']
productKeys.subResource('abc', 'reviews') // ['tanstack-query', 'products', 'detail', 'abc', 'reviews']
productKeys.byRelation('category', 'electronics') // ['tanstack-query', 'products', 'by-category', 'electronics']
`

实际项目中的组织方式：

`tsx
// src/queries/keys.ts
import { createDomainKeyFactory } from '@qiaopeng/tanstack-query-plus/core'

export const productKeys = createDomainKeyFactory('products')
export const orderKeys = createDomainKeyFactory('orders')
export const cartKeys = createDomainKeyFactory('cart')
export const reviewKeys = createDomainKeyFactory('reviews')

// 使用
import { productKeys } from '@/queries/keys'

useQuery({
queryKey: productKeys.detail(productId),
queryFn: () => fetchProduct(productId),
})
`

$3

本库还提供了一些高级的 Key 工具函数：

`tsx
import {
createFilteredKey,
createPaginatedKey,
createSortedKey,
createSearchKey,
createComplexKey,
matchesKeyPattern,
areKeysEqual
} from '@qiaopeng/tanstack-query-plus/core'

// 带筛选的 Key
const filteredKey = createFilteredKey(
productKeys.lists(),
{ category: 'electronics', inStock: true }
)
// ['tanstack-query', 'products', 'list', 'filtered', { category: 'electronics', inStock: true }]

// 带分页的 Key
const paginatedKey = createPaginatedKey(productKeys.lists(), 1, 20)
// ['tanstack-query', 'products', 'list', 'paginated', { page: 1, pageSize: 20 }]

// 带排序的 Key
const sortedKey = createSortedKey(productKeys.lists(), 'price', 'desc')
// ['tanstack-query', 'products', 'list', 'sorted', { sortBy: 'price', sortOrder: 'desc' }]

// 复杂查询 Key（组合多个条件）
const complexKey = createComplexKey(productKeys.lists(), {
page: 1,
pageSize: 20,
filters: { category: 'electronics' },
sortBy: 'price',
sortOrder: 'desc',
search: 'phone'
})

// 检查 Key 是否匹配模式
const matches = matchesKeyPattern(
['tanstack-query', 'products', 'detail', '123'],
['tanstack-query', 'products'] // 模式
)
// true - 可用于批量失效

// 比较两个 Key 是否相等
const equal = areKeysEqual(key1, key2)
`

$3

除了查询 Key，mutation 也可以有 Key（用于去重、追踪等）：

`tsx
import { createMutationKeyFactory } from '@qiaopeng/tanstack-query-plus/core'

const productMutations = createMutationKeyFactory('products')

productMutations.create() // ['products', 'create']
productMutations.update('123') // ['products', 'update', '123']
productMutations.delete('123') // ['products', 'delete', '123']
productMutations.batch('archive') // ['products', 'batch', 'archive']
`

现在你已经掌握了 Query Key 的管理。接下来，让我们学习如何进行数据变更（Mutation）以及如何实现乐观更新。

---

7. 第五步：数据变更与乐观更新


查询（Query）用于获取数据，而变更（Mutation）用于创建、更新或删除数据。本库的 useMutation 提供了内置的乐观更新支持，让用户体验更流畅。

$3

最基本的 mutation 使用：

`tsx
import { useMutation, useQueryClient } from '@qiaopeng/tanstack-query-plus'

function UpdateUserButton({ userId }) {
const queryClient = useQueryClient()

const mutation = useMutation({
mutationFn: (newName) =>
fetch(/api/users/${userId}, {
method: 'PATCH',
body: JSON.stringify({ name: newName })
}).then(r => r.json()),
onSuccess: () => {
// 成功后刷新用户数据
queryClient.invalidateQueries({ queryKey: ['user', userId] })
},
onError: (error) => {
alert(更新失败: ${error.message})
}
})

return (
onClick={() => mutation.mutate('新名字')}
disabled={mutation.isPending}
>
{mutation.isPending ? '更新中...' : '更新名字'}

)
}
`

$3

传统流程：
1. 用户点击"更新"
2. 显示 loading
3. 等待服务器响应
4. 更新 UI

乐观更新流程：
1. 用户点击"更新"
2. 立即更新 UI（假设会成功）
3. 后台发送请求
4. 如果失败，回滚到之前的状态

乐观更新让用户感觉应用响应更快，体验更好。

$3

本库的 useMutation 内置了乐观更新支持，无需手写复杂的 onMutate/onError 逻辑：

`tsx
import { useMutation } from '@qiaopeng/tanstack-query-plus/hooks'

function UpdateUserName({ userId, currentName }) {
const mutation = useMutation({
mutationFn: (newName) => updateUserAPI(userId, { name: newName }),

// 乐观更新配置
optimistic: {
queryKey: ['user', userId], // 要更新的缓存 key

// 更新函数：接收旧数据和变量，返回新数据
updater: (oldData, newName) => ({
...oldData,
name: newName
}),

// 回滚回调（可选）：失败时执行
rollback: (previousData, error) => {
console.error('更新失败，已回滚:', error.message)
toast.error(更新失败: ${error.message})
}
},

// 标准回调仍然可用
onSuccess: () => {
toast.success('更新成功')
}
})

return (
mutation.mutate('新名字')}>
更新名字

)
}
`

工作原理：

1. 调用 mutation.mutate('新名字') 时：
- 取消该 queryKey 的进行中请求
- 保存当前缓存数据（用于回滚）
- 调用 updater 立即更新缓存
- 发送实际请求

2. 如果请求成功：
- 自动失效该 queryKey，触发重新获取最新数据
- 调用 onSuccess 回调

3. 如果请求失败：
- 自动回滚到之前的数据
- 调用 rollback 回调
- 调用 onError 回调

$3

有时候 mutation 的变量名和缓存数据的字段名不一致，可以使用字段映射：

`tsx
const mutation = useMutation({
mutationFn: ({ newTitle }) => updateTodo(todoId, { title: newTitle }),

optimistic: {
queryKey: ['todo', todoId],
updater: (oldData, variables) => ({
...oldData,
...variables // 映射后的变量会自动应用
}),
// 将 mutation 变量的 newTitle 映射到缓存数据的 title
fieldMapping: {
'newTitle': 'title'
}
}
})

// 调用时
mutation.mutate({ newTitle: '新标题' })
// 缓存会更新 title 字段
`

$3

本库未提供单独的 useConditionalOptimisticMutation。如需按条件启用乐观更新，使用以下两种安全模式：

1. 使用两个 mutation，根据条件选择调用哪个（最清晰、类型安全）：

`tsx
import { useMutation } from '@qiaopeng/tanstack-query-plus/hooks'

const optimisticUpdate = useMutation({
mutationFn: updateTodo,
optimistic: {
queryKey: ['todos'],
updater: (oldTodos, updatedTodo) => oldTodos?.map(t => t.id === updatedTodo.id ? { ...t, ...updatedTodo } : t)
}
})

const plainUpdate = useMutation({ mutationFn: updateTodo })

function save(todo) {
const shouldOptimistic = todo.priority === 'high'
const runner = shouldOptimistic ? optimisticUpdate : plainUpdate
runner.mutate(todo)
}
`

2. 基于状态切换 optimistic.enabled（适合全局开关）：

`tsx
// 以应用自身配置或组件状态为准（此处仅示例）
const enableOptimistic = true
const mutation = useMutation({
mutationFn: updateTodo,
optimistic: {
queryKey: ['todos'],
enabled: enableOptimistic,
updater: (oldTodos, updatedTodo) => oldTodos?.map(t => t.id === updatedTodo.id ? { ...t, ...updatedTodo } : t)
}
})
`

$3

对于常见的列表 CRUD 操作，可以使用 useListMutation：

`tsx
import { useListMutation } from '@qiaopeng/tanstack-query-plus/hooks'

function TodoList() {
const mutation = useListMutation(
async ({ operation, data }) => {
switch (operation) {
case 'create':
return api.createTodo(data)
case 'update':
return api.updateTodo(data.id, data)
case 'delete':
return api.deleteTodo(data.id)
}
},
['todos'] // 操作完成后自动失效这个 queryKey
)

const handleCreate = () => {
mutation.mutate({
operation: 'create',
data: { title: '新任务', done: false }
})
}

const handleUpdate = (todo) => {
mutation.mutate({
operation: 'update',
data: { ...todo, done: !todo.done }
})
}

const handleDelete = (todoId) => {
mutation.mutate({
operation: 'delete',
data: { id: todoId }
})
}

// ...
}
`

$3

本库未提供 useBatchMutation。进行批量操作时，推荐两种模式：

1. 在一个 mutation 中封装批量逻辑（一次请求或并发 Promise）：

`tsx
import { useMutation } from '@qiaopeng/tanstack-query-plus/hooks'

const batchDelete = useMutation({
mutationFn: async (ids: string[]) => {
return Promise.all(ids.map(id => api.deleteTodo(id)))
},
optimistic: {
queryKey: ['todos'],
updater: (old, ids: string[]) => old?.filter(t => !ids.includes(String(t.id)))
}
})

// 使用
batchDelete.mutate(['id1', 'id2', 'id3'])
`

2. 使用离线队列在恢复网络后批量执行（稳健且可持久化）：

`tsx
import { createOfflineQueueManager, mutationRegistry, serializeMutationKey } from '@qiaopeng/tanstack-query-plus/features'
import { MutationOperationType } from '@qiaopeng/tanstack-query-plus/types'

const queue = createOfflineQueueManager({ storageKey: 'todo-ops', concurrency: 3 })

async function registerDelete(id: string) {
const key = serializeMutationKey(['todos', 'delete', id])
mutationRegistry.register(key, () => api.deleteTodo(id))
await queue.add({
type: MutationOperationType.DELETE,
mutationKey: ['todos', 'delete', id],
variables: { id },
mutationFn: () => api.deleteTodo(id),
priority: 1
})
}
`

$3

本库还提供了一些工具函数来简化列表的乐观更新：

`tsx
import {
listUpdater,
createAddItemConfig,
createUpdateItemConfig,
createRemoveItemConfig,
batchUpdateItems,
batchRemoveItems,
reorderItems,
conditionalUpdateItems
} from '@qiaopeng/tanstack-query-plus/utils'

// 列表更新器（要求列表项有 id 字段）
const list1 = listUpdater.add(items, newItem) // 添加到头部（如果 id 已存在则更新）
const list2 = listUpdater.update(items, { id: '1', title: '新标题' }) // 更新项
const list3 = listUpdater.remove(items, '1') // 按 id 移除项

// 创建预配置的乐观更新配置（返回 { queryKey, updater, rollback?, enabled } 对象）
const addConfig = createAddItemConfig(['todos'], {
addToTop: true, // 默认 true，添加到头部
onRollback: (error) => console.error('添加失败:', error)
})
const updateConfig = createUpdateItemConfig(['todos'])
const removeConfig = createRemoveItemConfig(['todos'])

// 在 mutation 中使用这些配置
const addMutation = useMutation({
mutationFn: createTodo,
optimistic: addConfig, // 直接使用预配置
})

// 批量更新（每个更新对象必须包含 id）
const list4 = batchUpdateItems(items, [
{ id: '1', done: true },
{ id: '2', done: true }
])

// 批量移除
const list5 = batchRemoveItems(items, ['1', '2', '3'])

// 重新排序（将 fromIndex 位置的项移动到 toIndex）
const list6 = reorderItems(items, 0, 2) // 将第一项移到第三位

// 条件更新（满足条件的项才更新）
const list7 = conditionalUpdateItems(
items,
(item) => item.status === 'pending', // 条件
(item) => ({ status: 'completed' }) // 更新内容
)
`

$3

`tsx
import { useEnhancedQuery, useMutation } from '@qiaopeng/tanstack-query-plus/hooks'
import { listUpdater } from '@qiaopeng/tanstack-query-plus/utils'

function TodoApp() {
// 查询 todos
const { data: todos, isLoading } = useEnhancedQuery({
queryKey: ['todos'],
queryFn: fetchTodos,
})

// 添加 todo（乐观更新）
const addMutation = useMutation({
mutationFn: (title) => api.createTodo({ title, done: false }),
optimistic: {
queryKey: ['todos'],
updater: (oldTodos, title) => [
{ id: temp-${Date.now()}, title, done: false },
...(oldTodos || [])
],
rollback: (_, error) => toast.error(添加失败: ${error.message})
}
})

// 切换完成状态（乐观更新）
const toggleMutation = useMutation({
mutationFn: (todo) => api.updateTodo(todo.id, { done: !todo.done }),
optimistic: {
queryKey: ['todos'],
updater: (oldTodos, todo) =>
oldTodos?.map(t => t.id === todo.id ? { ...t, done: !t.done } : t),
}
})

// 删除 todo（乐观更新）
const deleteMutation = useMutation({
mutationFn: (todoId) => api.deleteTodo(todoId),
optimistic: {
queryKey: ['todos'],
updater: (oldTodos, todoId) => oldTodos?.filter(t => t.id !== todoId),
}
})

if (isLoading) return

return (


- 明确回滚路径：在 onError 或 rollback 中恢复缓存或触发重新拉取
- 稳定的 queryKey：使用 Key 工厂，避免结构漂移导致更新不到位
- 变量安全：Mutation 变量不包含敏感信息（如 token），错误上报需脱敏
- 冲突处理：对 409 触发家族失效与 UI 提示；对 500 展示兜底提示并记录错误

现在你已经掌握了数据变更和乐观更新。接下来，让我们学习如何处理无限滚动和分页场景。

---

8. 第六步：无限滚动与分页


无限滚动是现代应用中常见的交互模式。本库提供了 useEnhancedInfiniteQuery 和多种分页模式的工厂函数，让实现变得简单。

$3

在实际项目中，后端 API 通常采用以下三种分页方式之一：

1. 游标分页（Cursor Pagination）
- 使用游标（通常是最后一条记录的 ID）来获取下一页
- 适合：社交媒体 feed、聊天记录
- 示例：/api/posts?cursor=abc123

2. 偏移分页（Offset Pagination）
- 使用 offset 和 limit 来获取数据
- 适合：传统列表、搜索结果
- 示例：/api/posts?offset=20&limit=10

3. 页码分页（Page Number Pagination）
- 使用页码来获取数据
- 适合：传统分页 UI
- 示例：/api/posts?page=2

$3

`tsx
import {
useEnhancedInfiniteQuery,
createCursorPaginationOptions
} from '@qiaopeng/tanstack-query-plus/hooks'

// 假设 API 返回格式：
// { items: [...], cursor: 'next-cursor' | null }

function PostFeed() {
// 创建游标分页配置
const options = createCursorPaginationOptions({
queryKey: ['posts', 'feed'],
queryFn: async (cursor) => {
const url = cursor
? /api/posts?cursor=${cursor}
: '/api/posts'
const response = await fetch(url)
return response.json()
// 返回 { items: Post[], cursor: string | null }
},
initialCursor: null, // 初始游标
staleTime: 30000,
})

const {
data,
fetchNextPage,
hasNextPage,
isFetchingNextPage,
isLoading,
} = useEnhancedInfiniteQuery(options)

if (isLoading) return

return (