本文介绍使用 tanstack query（react query）实现依赖型链式数据获取的最佳实践，通过 enabled 选项控制查询执行时机，避免竞态、状态混乱和手动 useeffect 嵌套，提升代码可维护性与健壮性。
本文介绍使用 tanstack query（react query）实现依赖型链式数据获取的最佳实践，通过 enabled 选项控制查询执行时机，避免竞态、状态混乱和手动 useeffect 嵌套，提升代码可维护性与健壮性。
在 React 应用中，当第二步 API 请求必须基于第一步响应中的字段（如 branchId）时，传统方式常采用嵌套 useEffect 或 async/await 链式调用，但这容易引发状态竞态、重复请求、加载逻辑耦合等问题。TanStack Query 提供的依赖查询（Dependent Queries）机制，是当前最推荐、最简洁、最可靠的解决方案。
✅ 核心原理：enabled 控制查询激活时机
TanStack Query 的 useQuery 支持 enabled: boolean 选项——仅当值为 true 时，查询才会自动触发。我们利用该特性，让第二步查询严格依赖第一步数据就绪：
import { useQuery } from "@tanstack/react-query";
// 第一步：获取 QR Code 数据
const { data: qrData, isLoading: isQrLoading, error: qrError } = useQuery({
queryKey: ["qrCode", id],
queryFn: () => getQrCode(id),
});
// 提取 branchId（安全访问，防止 undefined）
const branchId = qrData?.branchId;
// 第二步：仅当 branchId 存在时才发起请求
const {
data: branchData,
isLoading: isBranchLoading,
error: branchError,
status // 'success' | 'error' | 'pending'
} = useQuery({
queryKey: ["branch", branchId],
queryFn: () => getBranch(branchId!),
enabled: !!branchId, // 关键！确保 branchId 有效才执行
});
? 注意：enabled: !!branchId 是核心保障。即使 qrData 尚未返回或为 null，第二步查询将处于 idle 状态，不会报错或发送无效请求。
? 快速集成步骤
-
安装依赖
npm install @tanstack/react-query # 或 yarn add @tanstack/react-query
-
配置 QueryClientProvider（根组件）
// src/main.tsx 或 index.tsx import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; import ReactDOM from "react-dom/client"; import App from "./App"; const queryClient = new QueryClient(); ReactDOM.createRoot(document.getElementById("root")!).render( <queryclientprovider client="{queryClient}"><app></app></queryclientprovider> ); -
定义可复用的 queryKey（推荐）
// src/constants/queryKeys.ts export const QUERY_KEYS = { QR_CODE: (id: string) => ["qrCode", id] as const, BRANCH: (branchId: string) => ["branch", branchId] as const, };在组件中使用：
const { data: qrData } = useQuery({ queryKey: QUERY_KEYS.QR_CODE(id), queryFn: () => getQrCode(id), }); const { data: branchData } = useQuery({ queryKey: QUERY_KEYS.BRANCH(qrData?.branchId ?? ""), queryFn: () => getBranch(qrData!.branchId), enabled: !!qrData?.branchId, });
⚠️ 注意事项与最佳实践
- 不要手动管理 loading 状态：TanStack Query 自动提供 isLoading, isPending, isFetching 等精细化状态，优先使用 status === 'success' 判断渲染时机；
- 避免在 queryFn 中直接解构可能为 undefined 的数据：如 qrData?.branchId 应先校验再传入，或使用 enabled 拦截；
- 错误处理更清晰：分别监听 qrError 和 branchError，可针对性展示提示（如“二维码无效” vs “门店信息加载失败”）；
- 缓存与自动重试友好：两步查询独立缓存，且支持各自配置 retry, staleTime, gcTime，互不干扰；
- 跳过 useEffect 手动触发：完全告别 useEffect(() => { fetchA(); fetchB(); }, []) 这类易出错模式。
✅ 总结
链式数据获取的本质是声明式依赖控制，而非命令式执行顺序。TanStack Query 通过 enabled 实现了零成本的依赖编排，既消除了竞态风险，又大幅降低样板代码。相比手写 useEffect + useState 组合，它更健壮、更易测试、更利于后续扩展（如添加无限滚动、乐观更新等）。对于 Firebase 或任何 REST/GraphQL 后端，这都是现代 React 数据获取的标准范式。
