深入理解React-Query中的QueryClient核心功能

深入理解React-Query中的QueryClient核心功能

query 项目地址: https://gitcode.com/gh_mirrors/query13/query

React-Query作为现代React应用数据管理的利器，其核心QueryClient提供了强大的缓存管理能力。本文将全面解析QueryClient的功能和使用方法，帮助开发者掌握这一重要工具。

QueryClient基础概念

QueryClient是React-Query的核心控制器，负责管理查询缓存、数据获取和状态更新。通过它，开发者可以：

1. 预取数据优化用户体验
2. 手动控制缓存行为
3. 批量操作多个查询
4. 监控查询和变更状态

创建QueryClient实例时，可以配置默认选项：

import { QueryClient } from '@tanstack/react-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5, // 5分钟
      cacheTime: 1000 * 60 * 30 // 30分钟
    }
  }
})

数据获取与预取

同步获取数据

fetchQuery方法用于异步获取并缓存数据，它会返回Promise：

try {
  const data = await queryClient.fetchQuery({
    queryKey: ['todos'],
    queryFn: fetchTodos
  })
} catch (error) {
  // 处理错误
}

预取优化

prefetchQuery在用户需要数据前预先加载，提升用户体验：

// 在路由跳转前预取数据
const handleNavigate = async () => {
  await queryClient.prefetchQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId)
  })
  navigate('/user')
}

缓存操作详解

读取缓存数据

// 获取单个查询数据
const todoData = queryClient.getQueryData(['todos'])

// 获取多个查询数据
const allActiveData = queryClient.getQueriesData({
  predicate: query => query.isActive()
})

更新缓存数据

// 直接设置数据
queryClient.setQueryData(['todos'], newTodos)

// 使用更新函数
queryClient.setQueryData(['todo', id], oldData => 
  oldData ? {...oldData, completed: true} : oldData
)

批量更新

// 更新所有以"posts"开头的查询
queryClient.setQueriesData(
  { queryKey: ['posts'] },
  oldData => ({ ...oldData, updated: true })
)

查询状态管理

失效与重新获取

// 标记查询为失效并重新获取
await queryClient.invalidateQueries({
  queryKey: ['posts'],
  refetchType: 'active' // 只重新获取活跃查询
})

取消查询

// 取消所有posts查询
await queryClient.cancelQueries({ queryKey: ['posts'] })

重置查询状态

// 重置查询到初始状态
await queryClient.resetQueries({
  queryKey: ['user'],
  exact: true
})

高级功能与监控

默认选项配置

// 设置默认查询选项
queryClient.setDefaultOptions({
  queries: {
    retry: 3,
    retryDelay: attemptIndex => Math.min(1000 * 2 ** attemptIndex, 30000)
  }
})

状态监控

// 获取当前正在进行的查询数量
const fetchingCount = queryClient.isFetching()

// 获取当前正在进行的变更数量
const mutatingCount = queryClient.isMutating()

最佳实践建议

1. 预取策略：在用户可能访问的页面路径上预先加载数据
2. 缓存更新：在变更操作后及时更新相关缓存
3. 错误处理：为所有数据获取操作添加错误处理
4. 性能优化：合理设置staleTime和cacheTime
5. 内存管理：及时清理不再需要的查询

QueryClient的强大功能使得React应用的数据管理变得简单而高效。通过合理利用其提供的各种方法，开发者可以构建出响应迅速、用户体验优秀的应用程序。

query 项目地址: https://gitcode.com/gh_mirrors/query13/query