如何使用 TanStack Query 构建高效的异步状态管理层 #

解决前端开发中繁琐的 useEffect 数据请求痛点，通过 AI 引导实现声明式的数据获取、精细化的缓存控制以及高性能的乐观 UI 更新。

为什么需要这个技能 #

在传统的 React 开发中，处理异步数据通常依赖 useEffect 和 useState，这会导致代码冗余（如手动处理 loading 和 error 状态）、请求重复以及缓存缺失。

TanStack Query 不仅仅是一个请求库，而是一个异步状态管理器。它能自动处理请求去重、后台静默更新、分页以及复杂的缓存失效机制。掌握此技能可以让开发者从底层状态同步的琐事中解脱，将重心放在业务逻辑上。

适用场景 #

• 重构数据流：用 useQuery 替代繁琐的 useEffect 请求模式。
• 设计缓存策略：配置 staleTime（新鲜时间）和 gcTime（垃圾回收时间）以平衡性能与实时性。
• 提升用户体验：实现“乐观更新（Optimistic Updates）”，在服务器响应前立即更新 UI。
• 服务端渲染集成：在 Next.js App Router 中实现 Server Component 预取与客户端激活（Hydration）。

核心工作流 #

1. 封装自定义 Hook #

不要在组件内直接写 useQuery，应将其封装在自定义 Hook 中，以统一管理 TypeScript 类型和 Query Keys。

export const useUser = (userId: string) => {
  return useQuery({
    queryKey: ['users', userId], 
    queryFn: () => fetchUser(userId),
    staleTime: 1000 * 60 * 5, // 5 分钟内数据被视为新鲜
    enabled: !!userId, // 仅在 userId 存在时触发
  });
};

2. 缓存失效与数据变更 #

使用 useMutation 处理写操作，并在 onSuccess 回调中通过 invalidateQueries 通知客户端更新过期数据。

export const useCreatePost = () => {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: createPostFn,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['posts'] });
    },
  });
};

3. Next.js SSR 预取 #

在服务端组件中使用 prefetchQuery，通过 HydrationBoundary 将预取的数据传递给客户端，消除首屏加载白屏。

export default async function PostsPage() {
  const queryClient = new QueryClient();
  await queryClient.prefetchQuery({
    queryKey: ['posts'],
    queryFn: fetchPostsServerSide,
  });

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <PostsList />
    </HydrationBoundary>
  );
}

下载和安装 #

下载 tanstack-query-expert 中文版 Skill ZIP

解压后将目录放入你的 AI 工具 skills 文件夹，重启工具后即可使用。具体路径参考内附的 USAGE.zh.md。

你可能还需要 #

暂无推荐