React数据请求优化：TanStack Query实战指南

1. 从零到一：前端数据请求的演进之路

作为一名经历过jQuery时代的老前端，我亲眼见证了前端数据请求方式的多次迭代。最初我们使用XMLHttpRequest直接操作DOM，后来jQuery的$.ajax简化了流程，再到Fetch API的标准化，直到现在React生态中各种状态管理方案的百花齐放。

在React项目中，数据请求的演变尤为明显。早期的类组件时代，我们习惯在componentDidMount生命周期中发起请求，随着Hooks的普及，useEffect成为了新的选择。但很快我们就发现，仅仅使用useEffect管理请求存在诸多局限：

javascript复制// 典型的问题代码示例
useEffect(() => {
  let isMounted = true;
  const fetchData = async () => {
    try {
      const res = await fetch('/api/data');
      if (isMounted) setData(await res.json());
    } catch (err) {
      if (isMounted) setError(err);
    }
  };
  fetchData();
  return () => { isMounted = false; };
}, []);

这种模式需要手动处理组件卸载时的状态更新，容易造成内存泄漏。更不用说还要自行实现loading状态、错误处理、缓存策略等，每个项目都要重复造轮子。

2. TanStack Query的核心优势解析

2.1 开箱即用的状态管理

TanStack Query最直观的优势就是它将数据请求的三个核心状态（data、loading、error）封装成了一个简洁的Hook：

javascript复制const { data, isLoading, isError } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
});

这种设计让开发者不再需要手动维护这些状态，减少了大量样板代码。更重要的是，这些状态的更新是完全同步的，不会出现setState异步更新导致的竞态条件问题。

2.2 智能的请求缓存与去重

在实际项目中，经常会出现多个组件同时请求相同数据的情况。传统方式会导致重复请求，而TanStack Query会自动合并这些请求：

javascript复制// 组件A
const { data: user } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
});

// 组件B - 相同的queryKey不会重复请求
const { data: sameUser } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
});

这种机制不仅减少了不必要的网络请求，还能保证应用状态的一致性。当数据发生变化时，所有相关组件都会自动更新。

2.3 强大的数据同步能力

现代应用经常需要在不同页面间同步数据状态。TanStack Query通过queryClient提供了跨组件的数据同步方案：

javascript复制// 在任何组件中
const queryClient = useQueryClient();

// 使特定查询失效并重新获取
queryClient.invalidateQueries({ queryKey: ['user'] });

// 直接更新缓存数据
queryClient.setQueryData(['user', userId], newData);

这种能力让我们可以轻松实现如"编辑后刷新列表"、"删除后更新视图"等常见需求，而无需依赖复杂的状态管理或事件系统。

3. 实战：TanStack Query在复杂场景中的应用

3.1 分页与无限加载

对于列表数据，TanStack Query提供了专门的useInfiniteQuery Hook：

javascript复制const {
  data,
  fetchNextPage,
  hasNextPage,
} = useInfiniteQuery({
  queryKey: ['projects'],
  queryFn: ({ pageParam = 1 }) => fetchProjects(pageParam),
  getNextPageParam: (lastPage) => lastPage.nextPage,
});

// 渲染列表和加载更多按钮
{hasNextPage && (
  <button onClick={() => fetchNextPage()}>
    加载更多
  </button>
)}

这种实现方式比手动管理分页状态要简洁得多，而且内置了防重处理和loading状态管理。

3.2 乐观更新提升用户体验

在修改数据的场景下，我们可以使用useMutation实现乐观更新：

javascript复制const mutation = useMutation({
  mutationFn: updateTodo,
  onMutate: async (newTodo) => {
    // 取消正在进行的相同查询
    await queryClient.cancelQueries({ queryKey: ['todos'] });
    
    // 保存当前数据以便回滚
    const previousTodos = queryClient.getQueryData(['todos']);
    
    // 乐观更新
    queryClient.setQueryData(['todos'], (old) => 
      old.map(todo => todo.id === newTodo.id ? newTodo : todo)
    );
    
    return { previousTodos };
  },
  onError: (err, newTodo, context) => {
    // 出错时回滚
    queryClient.setQueryData(['todos'], context.previousTodos);
  },
  onSettled: () => {
    // 确保数据最终一致
    queryClient.invalidateQueries({ queryKey: ['todos'] });
  },
});

这种模式让UI能够立即响应，再在后台同步服务器状态，大幅提升了用户体验。

3.3 请求取消与竞态处理

TanStack Query内置了请求取消功能，可以自动处理组件卸载时的请求中断：

javascript复制useQuery({
  queryKey: ['data', id],
  queryFn: async ({ signal }) => {
    const res = await fetch(`/api/data/${id}`, { signal });
    return res.json();
  },
});

通过传递AbortSignal，当查询被取消或组件卸载时，正在进行的请求会被自动中止，避免内存泄漏和状态更新问题。

4. 性能优化与高级配置

4.1 缓存策略调优

TanStack Query的缓存行为可以通过多种参数精细控制：

javascript复制useQuery({
  queryKey: ['user', userId],
  queryFn: fetchUser,
  staleTime: 5 * 60 * 1000, // 5分钟内数据视为新鲜
  cacheTime: 30 * 60 * 1000, // 30分钟后从缓存移除
  refetchOnWindowFocus: true, // 窗口聚焦时重新验证
  refetchOnReconnect: true, // 网络恢复时重新验证
  retry: 2, // 失败后重试2次
});

这些配置可以根据数据特性进行调整。例如，实时性要求高的数据可以设置较短的staleTime，而静态数据可以设置较长的缓存时间。

4.2 预加载与数据预取

在用户可能访问的路径上提前加载数据：

javascript复制// 在用户hover链接时预加载
const onHover = () => {
  queryClient.prefetchQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
  });
};

这种技术可以显著提升页面切换时的用户体验，让数据看起来像是即时加载的。

4.3 服务端渲染支持

TanStack Query完美支持SSR场景，可以在服务端预取数据并注入到客户端：

javascript复制// 服务端
const queryClient = new QueryClient();
await queryClient.prefetchQuery(['user'], fetchUser);

// 将脱水数据传递给客户端
const dehydratedState = dehydrate(queryClient);

// 客户端
const queryClient = new QueryClient();
hydrate(queryClient, dehydratedState);

这种机制让同构应用的数据管理变得非常简单，同时保持了客户端的水合能力。

5. 常见问题与解决方案

5.1 TypeScript集成最佳实践

TanStack Query对TypeScript的支持非常完善，我们可以充分利用类型推断：

typescript复制interface User {
  id: string;
  name: string;
  email: string;
}

const { data: user } = useQuery<User>({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
});

// user现在有完整的类型提示
console.log(user?.name);

对于更复杂的场景，可以创建自定义Hook封装特定查询：

typescript复制function useUser(userId: string) {
  return useQuery<User>({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
  });
}

5.2 测试策略

测试TanStack Query相关的组件时，建议使用@tanstack/react-query-testing-library提供的工具：

javascript复制import { renderHook, waitFor } from '@testing-library/react';
import { useQuery } from '@tanstack/react-query';

test('should fetch data', async () => {
  const { result } = renderHook(() => 
    useQuery({ queryKey: ['test'], queryFn: () => 'data' })
  );

  await waitFor(() => expect(result.current.isSuccess).toBe(true));
  expect(result.current.data).toBe('data');
});

对于组件测试，需要包装QueryClientProvider：

javascript复制const queryClient = new QueryClient();
render(
  <QueryClientProvider client={queryClient}>
    <Component />
  </QueryClientProvider>
);

5.3 错误处理统一方案

建议在创建QueryClient时配置全局错误处理：

javascript复制const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      onError: (error) => {
        // 统一处理错误，如显示通知
        toast.error(error.message);
      },
    },
    mutations: {
      onError: (error) => {
        toast.error(error.message);
      },
    },
  },
});

对于特定查询的特殊处理，可以在useQuery/useMutation的onError回调中覆盖全局设置。

6. 迁移策略与渐进式采用

对于已有项目，可以采用渐进式迁移策略：

1. 从新功能开始使用TanStack Query
2. 逐步替换现有的useEffect数据请求
3. 最后处理复杂的跨组件数据共享场景

迁移时可以创建适配层，将现有API封装成TanStack Query兼容的形式：

javascript复制// 传统API适配器
function useLegacyQuery(apiCall, params) {
  return useQuery({
    queryKey: [apiCall.name, ...Object.values(params)],
    queryFn: () => apiCall(params),
  });
}

这种策略可以降低迁移风险，让团队逐步适应新的数据管理模式。