在现代 Web 开发中，高效地管理异步数据请求和缓存对于提升用户体验至关重要。TanStack/query（简称 query）是一款专注于异步状态管理的库，它不仅支持 React、Vue 等主流前端框架，还提供了丰富的功能来简化 API 请求管理和缓存处理。本文将详细介绍 TanStack/query 的核心功能和使用方法，帮助用户快速上手并掌握其精髓。
一、TanStack/query 简介
1.1 什么是 TanStack/query？
TanStack/query 是由 TanStack 团队开发的一款异步状态管理工具，旨在为前端开发者提供一种简单而强大的方式来处理 API 请求和缓存。它通过声明式的方式定义查询，并自动处理请求的生命周期、错误处理、重试机制等复杂逻辑。query 支持多种前端框架，如 React、Vue 和 Svelte，使得开发者能够轻松集成到现有项目中。
1.2 核心特性
- 声明式查询：通过简单的配置即可定义复杂的 API 请求。
- 自动缓存：内置了智能缓存机制，确保数据的一致性和性能优化。
- 实时更新：支持 WebSocket 和长轮询等方式实现数据的实时更新。
- 灵活配置：提供了丰富的选项来自定义查询行为，满足不同场景需求。
- 社区活跃：拥有庞大的用户群体和活跃的开发社区，提供了丰富的文档和资源。
二、安装与配置
2.1 安装 TanStack/query
要开始使用 TanStack/query，首先需要将其安装到项目中。可以通过 npm 或 yarn 来完成安装。
2.1.1 使用 npm 安装
npm install @tanstack/react-query
2.1.2 使用 yarn 安装
yarn add @tanstack/react-query
2.2 初始化 QueryClient
安装完成后，在项目的入口文件中初始化 QueryClient 实例，并将其传递给应用程序。
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
const queryClient = new QueryClient();
function App() {
return (
<QueryClientProvider client={queryClient}>
{/* 应用程序组件 */}
</QueryClientProvider>
);
}
三、基础功能
3.1 使用 useQuery 钩子
useQuery 是 TanStack/query 提供的核心钩子之一，用于发起 API 请求并管理查询结果。以下是一个简单的示例，展示如何使用 useQuery 获取用户列表。
import { useQuery } from '@tanstack/react-query';
import axios from 'axios';
function UsersList() {
const { isLoading, error, data } = useQuery('users', () =>
axios.get('/api/users').then((res) => res.data)
);
if (isLoading) return <div>Loading...</div>;
if (error) return <div>Error: {error.message}</div>;
return (
<ul>
{data.map((user) => (
<li key={user.id}>{user.name}</li>
))}
</ul>
);
}
3.2 查询选项
useQuery 支持多种选项来自定义查询行为，如设置缓存时间、启用或禁用查询、指定重试次数等。
const { data } = useQuery('todos', fetchTodos, {
staleTime: 1000 * 60, // 设置缓存时间为 1 分钟
cacheTime: 1000 * 60 * 5, // 设置缓存存活时间为 5 分钟
retry: false, // 禁用自动重试
});
3.3 查询失效与刷新
为了确保数据的新鲜度，TanStack/query 提供了多种方式来触发查询失效和刷新。
3.3.1 手动刷新
const { refetch } = useQuery('todos', fetchTodos);
// 触发手动刷新
refetch();
3.3.2 自动失效
useQuery('todos', fetchTodos, {
staleTime: 0, // 立即失效
});
四、高级功能
4.1 数据变换
在某些情况下，可能需要对原始数据进行转换。TanStack/query 提供了 select 选项，允许用户在获取数据后对其进行处理。
const { data } = useQuery('todos', fetchTodos, {
select: (todos) => todos.filter((todo) => !todo.completed),
});
4.2 依赖项
当查询依赖于其他变量时，可以将这些变量作为依赖项传递给 useQuery。
const [userId, setUserId] = useState(1);
const { data } = useQuery(['user', userId], () =>
fetchUserById(userId)
);
4.3 乐观更新
为了提高用户体验，可以在发起请求前先更新 UI，待请求成功后再同步实际数据。这被称为乐观更新。
const [newTodo, setNewTodo] = useState('');
const mutate = useMutation(addTodo, {
onMutate: (newTodo) => {
// 保存当前缓存快照
const previousTodos = queryClient.getQueryData('todos');
// 乐观更新缓存
queryClient.setQueryData('todos', (oldTodos) => [
...oldTodos,
newTodo,
]);
// 返回快照以便后续回滚
return { previousTodos };
},
onError: (error, variables, context) => {
// 请求失败时回滚缓存
queryClient.setQueryData('todos', context.previousTodos);
},
});
function handleSubmit(e) {
e.preventDefault();
mutate({ id: Date.now(), text: newTodo, completed: false });
setNewTodo('');
}
4.4 WebSocket 支持
对于需要实时更新的应用场景，TanStack/query 支持通过 WebSocket 或长轮询等方式实现数据的实时同步。
useEffect(() => {
const socket = new WebSocket('ws://localhost:8080');
socket.onmessage = (event) => {
const updatedTodo = JSON.parse(event.data);
queryClient.setQueryData('todos', (oldTodos) =>
oldTodos.map((todo) =>
todo.id === updatedTodo.id ? updatedTodo : todo
)
);
};
return () => socket.close();
}, []);
五、总结
TanStack/query 作为一款现代前端应用的异步状态管理利器，凭借其简洁的 API、高效的缓存机制和丰富的功能，已经成为众多开发者构建复杂 Web 应用的首选工具。从基础的 API 请求管理到高级的数据变换和实时更新，TanStack/query 提供了全方位的支持，使得用户能够灵活应对各种开发需求。
