React从基础入门到高级实战：React 生态与工具 - React Query：异步状态管理

React Query：异步状态管理

引言

在现代Web开发中，异步数据管理是React应用开发中的核心挑战之一。无论是从远程API获取数据、处理用户交互，还是同步服务器状态，开发者都需要一种高效、可靠的方式来应对这些复杂场景。传统的状态管理方案，如手动管理加载状态或借助Redux处理服务器数据，往往伴随着繁琐的样板代码和复杂的逻辑。而React Query的出现，为开发者提供了一种全新的解决方案。

React Query 是一个专注于异步状态管理的React库，它通过简洁的API、强大的缓存机制和自动化的错误处理功能，极大简化了服务器状态的管理过程。无论是初学者还是经验丰富的开发者，React Query都能帮助他们更高效地构建健壮的应用程序，同时提升用户体验。

本文将全面介绍React Query的核心特性与使用方法，包括查询与突变的概念、钩子的配置与使用、缓存与重试机制，以及与Redux的对比分析。此外，我们将通过一个实际的用户列表案例和一个带缓存的搜索功能练习，展示React Query在真实开发场景中的应用价值。希望通过这篇深度文章，您能掌握React Query的核心思想，并在项目中灵活运用。

---

一、React Query的核心概念

React Query的核心在于其对异步数据管理的抽象，主要通过**查询（Queries）和突变（Mutations）**两个概念实现。

1.1 查询（Queries）

查询是React Query中用于从服务器获取数据的基本单元。每个查询通过一个唯一的**查询键（Query Key）标识，并与一个返回Promise的查询函数（Query Function）**关联。React Query会自动管理查询的状态（如加载中、成功或失败），开发者只需关注数据的获取逻辑。

查询键（Query Key）

查询键可以是字符串或数组，用于标识特定的数据。例如：

• 'todos'：表示所有待办事项。
• ['todos', userId]：表示特定用户的待办事项。

查询键不仅是数据的标识符，也是React Query缓存机制的基础。合理的查询键设计能够确保数据的高效复用和更新。

查询函数（Query Function）

查询函数是一个异步函数，通常用于调用API。例如：

const fetchTodos = async () => {
  const response = await fetch('/api/todos');
  return response.json();
};

通过useQuery钩子，我们可以将查询键和查询函数结合起来：

const { data, isLoading, error } = useQuery('todos', fetchTodos);

在这里，data表示获取到的数据，isLoading表示加载状态，error表示可能的错误。

1.2 突变（Mutations）

突变用于处理数据的修改操作，例如创建、更新或删除数据。与查询不同，突变通常会影响服务器状态，并可能需要同步本地缓存。

突变函数（Mutation Function）

突变函数同样是一个返回Promise的异步函数。例如：

const createTodo = async (newTodo) => {
  const response = await fetch('/api/todos', {
    method: 'POST',
    body: JSON.stringify(newTodo),
    headers: { 'Content-Type': 'application/json' },
  });
  return response.json();
};

使用useMutation

通过useMutation钩子，我们可以定义和管理突变：

const mutation = useMutation(createTodo, {
  onSuccess: () => {
    // 更新成功后，刷新todos查询
    queryClient.invalidateQueries('todos');
  },
});

mutation.mutate({ title: '新任务' });

在这里，mutate方法触发突变，onSuccess回调确保本地数据与服务器保持一致。

乐观更新（Optimistic Updates）

React Query支持乐观更新，即在突变完成前先更新本地数据，提升用户体验。例如：

const mutation = useMutation(createTodo, {
  onMutate: async (newTodo) => {
    await queryClient.cancelQueries('todos');
    const previousTodos = queryClient.getQueryData('todos');
    queryClient.setQueryData('todos', (old) => [...old, newTodo]);
    return { previousTodos };
  },
  onError: (err, newTodo, context) => {
    queryClient.setQueryData('todos', context.previousTodos);
  },
  onSettled: () => {
    queryClient.invalidateQueries('todos');
  },
});

这种方式在网络请求完成前就展示了更新后的UI，并在出错时回滚。

---

二、配置与使用

React Query提供了两个核心钩子：useQuery和useMutation，以及一个全局管理工具QueryClient。以下是它们的基本用法和配置方法。

2.1 useQuery钩子

useQuery用于获取数据并管理其状态。它接受三个主要参数：

• 查询键（Query Key）
• 查询函数（Query Function）
• 配置对象（可选）

基本用法

const { data, isLoading, isError, error } = useQuery('todos', fetchTodos);

• data：成功获取的数据。
• isLoading：是否正在加载。
• isError：是否发生错误。
• error：错误详情。

配置选项

useQuery支持丰富的配置选项，例如：

const { data } = useQuery('todos', fetchTodos, {
  staleTime: 1000 * 60 * 5, // 数据新鲜时间：5分钟
  cacheTime: 1000 * 60 * 10, // 缓存时间：10分钟
  refetchOnWindowFocus: false, // 窗口聚焦时不重新获取
});

这些选项允许开发者根据需求调整数据获取行为。

2.2 useMutation钩子

useMutation用于执行数据更新操作。它接受突变函数和配置对象。

基本用法

const mutation = useMutation(createTodo);
mutation.mutate({ title: '新任务' });

• mutate：触发突变的方法。
• isLoading：突变是否正在进行。
• isError和error：错误状态和信息。

配置选项

const mutation = useMutation(createTodo, {
  onSuccess: (data) => {
    console.log('创建成功:', data);
    queryClient.invalidateQueries('todos');
  },
  onError: (error) => {
    console.error('创建失败:', error);
  },
});

这些回调函数帮助开发者处理突变的不同阶段。

2.3 QueryClient和QueryClientProvider

QueryClient是React Query的管理核心，负责缓存、配置和状态管理。通过QueryClientProvider，我们将QueryClient注入到React组件树中。

配置QueryClient

import { QueryClient, QueryClientProvider } from 'react-query';

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      retry: 3, // 默认重试3次
      cacheTime: 1000 * 60 * 5, // 默认缓存5分钟
    },
  },
});

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      {/* 应用组件 */}
    </QueryClientProvider>
  );
}

---

三、缓存与重试

React Query的缓存和重试机制是其核心优势之一，能够显著优化网络请求和提升应用性能。

3.1 缓存机制

React Query会自动缓存查询结果，并根据查询键进行复用。缓存行为由以下参数控制：

• 陈旧时间（Stale Time）：数据被认为是新鲜的时间，默认0秒。数据新鲜时不会重新请求。
• 缓存时间（Cache Time）：数据在缓存中保留的时间，默认5分钟。超出后数据会被垃圾回收。

示例

useQuery('todos', fetchTodos, {
  staleTime: 1000 * 60 * 5, // 5分钟内数据新鲜
  cacheTime: 1000 * 60 * 10, // 缓存保留10分钟
});

如果组件在5分钟内重新挂载，React Query会直接返回缓存数据，无需发起请求。

手动管理缓存

QueryClient提供了方法来操作缓存：

• setQueryData：手动更新缓存数据。
• invalidateQueries：标记查询为失效，触发重新获取。

queryClient.setQueryData('todos', (old) => [...old, newTodo]);
queryClient.invalidateQueries('todos');

3.2 自动重试

React Query内置了失败重试机制，默认重试3次。开发者可以通过配置自定义重试行为：

useQuery('todos', fetchTodos, {
  retry: 5, // 重试5次
  retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 30000), // 指数退避
});

这种机制在网络不稳定时尤为有用，能提高应用的健壮性。

---

四、与Redux的对比

React Query和Redux都是状态管理工具，但它们的目标和实现方式有显著差异。

4.1 状态管理范式

• Redux：集中式状态管理，适用于UI状态和业务逻辑状态，遵循单向数据流。
• React Query：专注于异步状态（服务器状态），将数据获取与UI状态解耦。

4.2 复杂性

• Redux：需要编写actions、reducers和selectors，代码量较大。
• React Query：提供声明式API，减少样板代码，开发者只需定义查询和突变。

4.3 缓存和性能

• Redux：无内置缓存，需手动实现数据的存储和更新。
• React Query：内置缓存和自动更新机制，优化网络请求。

4.4 适用场景

• Redux：适合复杂应用状态管理，如跨组件共享的UI状态。
• React Query：适合管理API数据，简化异步操作。

综合使用

在实际项目中，Redux和React Query可以结合使用：Redux管理本地状态，React Query处理服务器状态。

---

五、案例：用户列表

让我们通过一个实际案例，展示React Query如何实现分页和实时更新的用户列表。

5.1 需求

• 从API获取用户列表。
• 支持分页加载（每次加载10条）。
• 支持下拉刷新实时更新。

5.2 实现

我们使用useInfiniteQuery实现分页加载：

import { useInfiniteQuery } from 'react-query';

const fetchUsers = async ({ pageParam = 1 }) => {
  const response = await fetch(`/api/users?page=${pageParam}`);
  return response.json(); // 返回 { users: [], nextPage: number | null }
};

function UserList() {
  const {
    data,
    fetchNextPage,
    hasNextPage,
    isFetchingNextPage,
    refetch,
  } = useInfiniteQuery('users', fetchUsers, {
    getNextPageParam: (lastPage) => lastPage.nextPage,
  });

  return (
    <div>
      <button onClick={() => refetch()}>刷新</button>
      {data?.pages.map((page, i) => (
        <div key={i}>
          {page.users.map((user) => (
            <div key={user.id}>{user.name}</div>
          ))}
        </div>
      ))}
      {hasNextPage && (
        <button onClick={() => fetchNextPage()} disabled={isFetchingNextPage}>
          {isFetchingNextPage ? '加载中...' : '加载更多'}
        </button>
      )}
    </div>
  );
}

5.3 分析

• useInfiniteQuery：支持无限滚动，分页数据存储在data.pages中。
• getNextPageParam：根据API返回的nextPage决定是否继续加载。
• refetch：手动触发刷新，实现实时更新。

---

六、练习：实现一个搜索功能，带缓存

6.1 需求

实现一个搜索框，用户输入关键词后从API获取结果，并缓存数据以避免重复请求。

6.2 实现

import { useQuery } from 'react-query';
import { useState } from 'react';

const fetchSearchResults = async (term) => {
  const response = await fetch(`/api/search?q=${term}`);
  return response.json();
};

function Search() {
  const [searchTerm, setSearchTerm] = useState('');
  const { data, isLoading } = useQuery(
    ['search', searchTerm],
    () => fetchSearchResults(searchTerm),
    {
      enabled: !!searchTerm, // 仅在searchTerm不为空时查询
      staleTime: 1000 * 60, // 缓存1分钟
    }
  );

  return (
    <div>
      <input
        type="text"
        value={searchTerm}
        onChange={(e) => setSearchTerm(e.target.value)}
        placeholder="输入搜索关键词"
      />
      {isLoading ? (
        <div>加载中...</div>
      ) : (
        <div>
          {data?.map((result) => (
            <div key={result.id}>{result.title}</div>
          ))}
        </div>
      )}
    </div>
  );
}

6.3 分析

• 查询键['search', searchTerm]：动态生成，确保不同关键词缓存独立。
• enabled选项：避免空查询触发请求。
• staleTime：缓存1分钟，提升性能。

---

七、注意事项

React Query的简洁性和易用性是其最大优势，但在使用时需注意以下几点：

1. 查询键设计 ：使用数组形式的查询键（如['todos', userId]），支持更灵活的缓存和更新。
2. 错误处理 ：利用isError和error状态，提供友好的用户反馈。
3. 性能优化 ：调整staleTime和cacheTime，平衡数据新鲜度和网络请求频率。
4. 与现有工具集成：React Query可与Redux、Context等配合使用，互补优势。

---

结语

React Query以其声明式API、强大的缓存和重试机制，为异步状态管理带来了革命性的改变。它不仅简化了开发流程，还通过优化网络请求提升了应用的性能和用户体验。无论是构建简单的原型还是复杂的企业应用，React Query都是一个值得信赖的工具。

通过本文的介绍和实践，希望您能充分理解React Query的核心价值，并在未来的开发中灵活运用。让我们拥抱这种现代化的状态管理方式，打造更高效、更优雅的React应用！