Python开发者的TanStack前端全栈学习指南

从Python后端转向前端开发是一个令人兴奋的转型。作为有后端经验的开发者，你已经具备了系统思维和架构理解能力，这将是你学习现代前端开发的巨大优势。本文将为你规划一条系统性的学习路径，重点掌握TanStack生态系统。

1. 学习路线图概览

graph TD
    A[Python 后端基础] --> B[前端基础强化]
    B --> C[React 生态系统]
    C --> D[TanStack 核心库]
    D --> E[项目实战]

    B --> B1[JavaScript/TS 强化]
    B --> B2[现代 CSS 与工程化]
    B --> B3[前端构建工具]

    C --> C1[React 核心概念]
    C --> C2[状态管理模式]
    C --> C3[现代 React Hooks]

    D --> D1[TanStack Query]
    D --> D2[TanStack Table]
    D --> D3[TanStack Router]
    D --> D4[TanStack Form]

    E --> E1[管理后台项目]
    E --> E2[性能优化实践]
    E --> E3[部署与监控]

2. 阶段一：前端基础强化 (2-3 周)

2.1 JavaScript/TypeScript 深度理解

作为Python开发者，你需要理解两种语言的核心差异：

对比学习法：Python vs JavaScript/TypeScript

| 概念 | Python | JavaScript/TypeScript | 关键差异 | |------|--------|----------------------|----------| | 变量声明 | name = "value" | let/const/var | 作用域与提升机制 | | 类型系统 | 动态 + 类型提示 | 动态 + 静态类型 | TS 编译时类型检查 | | 异步处理 | async/await | async/await + Promise | 事件循环机制 | | 面向对象 | class | class + 原型链 | 原型继承机制 | | 函数式编程 | lambda, map | 箭头函数, map/filter | 一等公民函数 |

必掌握的核心概念

闭包与作用域链

// Python中闭包概念
def outer_function(x):
    def inner_function(y):
        return x + y  # x 被闭包捕获
    return inner_function

// TypeScript中的闭包
function outerFunction(x: number) {
  return function innerFunction(y: number): number {
    return x + y;  // x 被闭包捕获
  };
}

const add5 = outerFunction(5);
console.log(add5(3)); // 8

this 绑定规则

// Python的self隐式绑定
class MyClass:
    def method(self):
        return self.value

// TypeScript的显式this绑定
class MyClass {
  value: number = 42;

  method = () => {  // 箭头函数自动绑定this
    return this.value;
  };

  traditionalMethod() {
    return this.value;  // 需要注意调用方式
  }
}

Promise 与异步处理

// Python异步
async def fetch_data():
    response = await requests.get('https://api.example.com')
    return response.json()

// TypeScript异步（更复杂的事件循环）
async function fetchData(): Promise<any> {
  try {
    const response = await fetch('https://api.example.com');
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return await response.json();
  } catch (error) {
    console.error('Fetch error:', error);
    throw error;
  }
}

2.2 TypeScript 类型系统深度

TypeScript 的类型系统远比 Python 的类型提示严格和强大：

// 高级类型特性
type ApiResponse<T> = {
  data: T;
  status: 'success' | 'error';
  timestamp: number;
};

// 条件类型
type NonNullable<T> = T extends null | undefined ? never : T;

// 映射类型
type Partial<T> = {
  [P in keyof T]?: T[P];
};

// 泛型约束
interface Lengthwise {
  length: number;
}

function loggingIdentity<T extends Lengthwise>(arg: T): T {
  console.log(arg.length);  // 现在知道arg有length属性
  return arg;
}

2.3 现代 CSS 与布局

从后端转向前端，你需要掌握现代 CSS 布局系统：

Flexbox 布局

/* 类似于Python的GUI布局管理器 */
.container {
  display: flex;
  justify-content: space-between;  # 类似于 pack="expand"
  align-items: center;            # 类似于 align="center"
  gap: 1rem;                     # 类似于 padding
}

.item {
  flex: 1;  # 类似于 expand=True
}

Grid 布局

.dashboard {
  display: grid;
  grid-template-columns: 250px 1fr 300px;  # 侧边栏 + 主内容 + 右侧栏
  grid-template-rows: auto 1fr auto;       # 头部 + 主内容 + 底部
  min-height: 100vh;
}

3. 阶段二：React 生态系统 (2-3 周)

3.1 核心思维转变

从后端的请求-响应模式转向前端的状态管理模式：

// 后端思维：Django/FastAPI
def get_user(request, user_id):
    user = User.objects.get(id=user_id)
    return render(request, 'user.html', {'user': user})
# 请求 -> 处理 -> 响应 -> 结束

// 前端思维：React
function UserProfile({ userId }: { userId: string }) {
  const [user, setUser] = useState<User | null>(null);

  // 状态持续存在，需要手动管理生命周期
  useEffect(() => {
    fetchUser(userId).then(setUser);
  }, [userId]);

  // 状态变化 -> UI 自动更新
  return <div>{user?.name}</div>;
}

3.2 React Hooks 深度理解

useState vs Python 变量

// Python中的变量管理
def component():
    user_data = get_user()  # 每次调用都重新获取
    return render_template('user.html', user=user_data)

// React中的状态管理
function UserComponent() {
  const [user, setUser] = useState<User | null>(null);  # 持久化状态

  // 只有当userId变化时才重新获取
  useEffect(() => {
    if (userId) {
      fetchUser(userId).then(setUser);
    }
  }, [userId]);
}

自定义 Hooks（逻辑复用）

// 类似于Python的装饰器或mixin
function useUserData(userId: string) {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    setLoading(true);
    fetchUser(userId)
      .then(setUser)
      .catch(setError)
      .finally(() => setLoading(false));
  }, [userId]);

  return { user, loading, error };
}

// 使用
function UserProfile({ userId }: { userId: string }) {
  const { user, loading, error } = useUserData(userId);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;
  return <div>{user?.name}</div>;
}

4. 阶段三：TanStack 核心库学习 (3-4 周)

4.1 TanStack Query：异步状态管理

这是 TanStack 生态的基石，也是理解现代前端数据流的关键：

核心理念：把后端的缓存思维带到前端

// 传统前端思维（类似每次API调用）
function UserList() {
  const [users, setUsers] = useState<User[]>([]);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    setLoading(true);
    fetchUsers().then(data => {
      setUsers(data);
      setLoading(false);
    });
  }, []);  // 依赖数组管理复杂，容易出错

  return loading ? <Loading /> : <UserList users={users} />;
}

// TanStack Query思维（智能缓存）
function UserList() {
  const {
    data: users,
    isLoading,
    error,
    refetch  // 手动刷新
  } = useQuery({
    queryKey: ['users'],  // 查询键，类似缓存键
    queryFn: fetchUsers,  // 数据获取函数
    staleTime: 5 * 60 * 1000,  // 5分钟内认为数据新鲜
    cacheTime: 10 * 60 * 1000, // 10分钟后清理缓存
  });

  if (isLoading) return <Loading />;
  if (error) return <Error error={error} />;

  return (
    <div>
      <button onClick={() => refetch()}>刷新</button>
      <UserList users={users} />
    </div>
  );
}

高级特性：乐观更新

// 类似于数据库的事务处理
const updateUser = useMutation({
  mutationFn: async (userData: Partial<User>) => {
    const response = await updateUserAPI(userData);
    return response.data;
  },

  // 乐观更新：立即更新UI，假设请求会成功
  onMutate: async (newUserData) => {
    // 取消正在进行的查询
    await queryClient.cancelQueries({ queryKey: ['users'] });

    // 获取当前数据快照
    const previousUsers = queryClient.getQueryData(['users']);

    // 乐观更新
    queryClient.setQueryData(['users'], (old: User[]) =>
      old?.map(user =>
        user.id === newUserData.id
          ? { ...user, ...newUserData }
          : user
      )
    );

    return { previousUsers };
  },

  // 如果失败，回滚到之前的状态
  onError: (err, newUserData, context) => {
    queryClient.setQueryData(['users'], context?.previousUsers);
  },

  // 无论成功失败，重新获取数据
  onSettled: () => {
    queryClient.invalidateQueries({ queryKey: ['users'] });
  },
});

4.2 TanStack Table：Headless UI 表格

理解 Headless UI 概念：数据处理与UI渲染分离

// 类似于后端的ORM，只处理数据逻辑
const table = useReactTable({
  data: users,  // 原始数据
  columns: [    // 列定义
    {
      accessorKey: 'name',
      header: '姓名',
      cell: (info) => info.getValue(),
    },
    {
      accessorKey: 'email',
      header: '邮箱',
      cell: (info) => info.getValue(),
    },
    {
      accessorKey: 'status',
      header: '状态',
      cell: (info) => (
        <span className={`status-${info.getValue()}`}>
          {info.getValue()}
        </span>
      ),
    },
  ],

  // 功能插件（类似中间件）
  getCoreRowModel: getCoreRowModel(),
  getSortedRowModel: getSortedRowModel(),    // 排序
  getFilteredRowModel: getFilteredRowModel(), // 筛选
  getPaginationRowModel: getPaginationRowModel(), // 分页
});

// 你只需要渲染UI（完全控制样式）
return (
  <div className="table-container">
    <table>
      <thead>
        {table.getHeaderGroups().map(headerGroup => (
          <tr key={headerGroup.id}>
            {headerGroup.headers.map(header => (
              <th key={header.id}>
                {flexRender(
                  header.column.columnDef.header,
                  header.getContext()
                )}
              </th>
            ))}
          </tr>
        ))}
      </thead>
      <tbody>
        {table.getRowModel().rows.map(row => (
          <tr key={row.id}>
            {row.getVisibleCells().map(cell => (
              <td key={cell.id}>
                {flexRender(
                  cell.column.columnDef.cell,
                  cell.getContext()
                )}
              </td>
            ))}
          </tr>
        ))}
      </tbody>
    </table>

    {/* 分页控制 */}
    <div className="pagination">
      <button onClick={() => table.setPageIndex(0)}>
        首页
      </button>
      <button
        onClick={() => table.previousPage()}
        disabled={!table.getCanPreviousPage()}
      >
        上一页
      </button>
      <button
        onClick={() => table.nextPage()}
        disabled={!table.getCanNextPage()}
      >
        下一页
      </button>
      <button onClick={() => table.setPageIndex(table.getPageCount() - 1)}>
        末页
      </button>
    </div>
  </div>
);

4.3 TanStack Router：类型安全的路由

类似于后端的路由系统，但提供编译时类型检查：

// 路由定义（类型安全）
const routeTree = rootRoute.createChildren({
  users: usersRoute.createChildren({
    ':userId': userRoute,  // 动态参数
  }),
  posts: postsRoute.createChildren({
    ':postId': postRoute,
  }),
});

// 自动类型推断的路由组件
function UserProfile() {
  // 参数自动推断为string类型
  const { userId } = useParams({ strict: false });

  // 搜索参数也有类型推断
  const [searchParams] = useSearch({
    from: '/users/$userId',
  });

  // 导航也有类型安全
  const navigate = useNavigate({ from: '/users/$userId' });

  const handleEdit = () => {
    navigate({
      to: '/users/$userId/edit',
      params: { userId },
      search: { tab: 'profile' }  // 类型安全的搜索参数
    });
  };

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

  if (isLoading) return <div>Loading...</div>;
  if (!user) return <div>User not found</div>;

  return (
    <div>
      <h1>{user.name}</h1>
      <p>Email: {user.email}</p>
      <button onClick={handleEdit}>编辑</button>
    </div>
  );
}

4.4 TanStack Form：复杂表单管理

类似于后端的表单验证系统，但运行在客户端：

// 类似于Django Forms或Pydantic模型
const userForm = useForm({
  defaultValues: {
    username: '',
    email: '',
    profile: {
      firstName: '',
      lastName: '',
      avatar: '',
    },
    preferences: {
      theme: 'light' as 'light' | 'dark',
      notifications: true,
    },
  },

  // 类似于后端验证器
  validators: {
    onChange: z.object({
      username: z.string()
        .min(3, '用户名至少3个字符')
        .max(20, '用户名最多20个字符')
        .regex(/^[a-zA-Z0-9_]+$/, '只能包含字母、数字和下划线'),

      email: z.string()
        .email('请输入有效的邮箱地址'),

      profile: z.object({
        firstName: z.string().min(1, '请输入名字'),
        lastName: z.string().min(1, '请输入姓氏'),
      }),
    }),

    // 异步验证（类似后端唯一性检查）
    onBlur: z.object({
      username: z.string().superRefine(async (username, ctx) => {
        if (username.length >= 3) {
          const exists = await checkUsernameExists(username);
          if (exists) {
            ctx.addIssue({
              code: z.ZodIssueCode.custom,
              message: '用户名已存在',
            });
          }
        }
      }),
    }),
  },
});

function UserForm() {
  const form = userForm;

  const handleSubmit = async (values: typeof form.values) => {
    try {
      await createUser(values);
      // 成功后的处理
      form.reset();
    } catch (error) {
      // 错误处理
      form.setError('root', { message: '创建用户失败' });
    }
  };

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        form.handleSubmit();
      }}
    >
      {/* 基本字段 */}
      <form.Field name="username">
        {(field) => (
          <div>
            <label>用户名</label>
            <input
              name={field.name}
              value={field.state.value}
              onChange={(e) => field.handleChange(e.target.value)}
              placeholder="输入用户名"
            />
            {field.state.meta.errors && (
              <div className="error">
                {field.state.meta.errors.join(', ')}
              </div>
            )}
          </div>
        )}
      </form.Field>

      <form.Field name="email">
        {(field) => (
          <div>
            <label>邮箱</label>
            <input
              name={field.name}
              type="email"
              value={field.state.value}
              onChange={(e) => field.handleChange(e.target.value)}
              placeholder="输入邮箱"
            />
            {field.state.meta.errors && (
              <div className="error">
                {field.state.meta.errors.join(', ')}
              </div>
            )}
          </div>
        )}
      </form.Field>

      {/* 嵌套对象字段 */}
      <form.Field name="profile.firstName">
        {(field) => (
          <div>
            <label>名字</label>
            <input
              name={field.name}
              value={field.state.value}
              onChange={(e) => field.handleChange(e.target.value)}
            />
            {field.state.meta.errors && (
              <div className="error">
                {field.state.meta.errors.join(', ')}
              </div>
            )}
          </div>
        )}
      </form.Field>

      {/* 选项字段 */}
      <form.Field name="preferences.theme">
        {(field) => (
          <div>
            <label>主题</label>
            <select
              name={field.name}
              value={field.state.value}
              onChange={(e) => field.handleChange(e.target.value as 'light' | 'dark')}
            >
              <option value="light">浅色</option>
              <option value="dark">深色</option>
            </select>
          </div>
        )}
      </form.Field>

      <button
        type="submit"
        disabled={form.isSubmitting}
      >
        {form.isSubmitting ? '创建中...' : '创建用户'}
      </button>
    </form>
  );
}

5. 阶段四：项目实战 (4-5 周)

5.1 综合项目：SaaS 管理后台

这是一个结合所有TanStack技术的完整项目：

项目需求

• 用户管理模块（CRUD + 权限控制）
• 订单管理模块（复杂表格 + 筛选排序）
• 数据统计模块（图表 + 实时更新）
• 系统设置模块（复杂表单验证）

技术栈整合

// 完整的应用架构
import {
  QueryClient,
  QueryClientProvider,
} from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { RouterProvider, createRouter } from '@tanstack/react-router';

// 1. 配置Query Client
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000, // 5分钟
      cacheTime: 10 * 60 * 1000, // 10分钟
      retry: (failureCount, error) => {
        // 4xx错误不重试，5xx错误重试2次
        if (error.status >= 400 && error.status < 500) {
          return false;
        }
        return failureCount < 2;
      },
    },
    mutations: {
      retry: 1,
    },
  },
});

// 2. 创建路由
const router = createRouter({
  routeTree,
  defaultPreload: 'intent',
});

// 3. 应用根组件
function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <RouterProvider router={router} />
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}

// 4. 用户管理页面组件
function UsersPage() {
  // TanStack Query 获取用户数据
  const {
    data: users = [],
    isLoading,
    error
  } = useQuery({
    queryKey: ['users'],
    queryFn: fetchUsers,
  });

  // TanStack Table 管理表格状态
  const table = useReactTable({
    data: users,
    columns: userColumns,
    getCoreRowModel: getCoreRowModel(),
    getSortedRowModel: getSortedRowModel(),
    getFilteredRowModel: getFilteredRowModel(),
    getPaginationRowModel: getPaginationRowModel(),
  });

  // TanStack Form 处理用户创建
  const createUserForm = useForm({
    defaultValues: {
      name: '',
      email: '',
      role: 'user',
      status: 'active',
    },
    validators: {
      onChange: createUserValidator,
    },
  });

  const createUserMutation = useMutation({
    mutationFn: createUserAPI,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['users'] });
      createUserForm.reset();
    },
  });

  if (isLoading) return <UserListSkeleton />;
  if (error) return <ErrorMessage error={error} />;

  return (
    <div className="users-page">
      {/* 页面头部 */}
      <div className="page-header">
        <h1>用户管理</h1>
        <button onClick={() => setShowCreateModal(true)}>
          创建用户
        </button>
      </div>

      {/* 筛选器 */}
      <UserFilters table={table} />

      {/* 用户表格 */}
      <UserTable table={table} />

      {/* 分页 */}
      <TablePagination table={table} />

      {/* 创建用户模态框 */}
      {showCreateModal && (
        <CreateUserModal
          form={createUserForm}
          onSubmit={(values) => createUserMutation.mutate(values)}
          onClose={() => setShowCreateModal(false)}
        />
      )}
    </div>
  );
}

项目结构建议

src/
├── components/          # 可复用组件
│   ├── ui/             # 基础UI组件（Button、Input等）
│   ├── forms/          # 表单相关组件
│   ├── tables/         # 表格相关组件
│   └── layout/         # 布局组件
├── pages/              # 页面组件
│   ├── users/          # 用户管理
│   ├── orders/         # 订单管理
│   ├── analytics/      # 数据分析
│   └── settings/       # 系统设置
├── hooks/              # 自定义Hooks
│   ├── useUsers.ts     # 用户相关逻辑
│   ├── useOrders.ts    # 订单相关逻辑
│   └── useAuth.ts      # 认证相关逻辑
├── services/           # API服务
│   ├── api.ts          # API客户端配置
│   ├── users.ts        # 用户API
│   └── orders.ts       # 订单API
├── types/              # TypeScript类型定义
│   ├── user.ts         # 用户类型
│   ├── order.ts        # 订单类型
│   └── api.ts          # API响应类型
├── utils/              # 工具函数
│   ├── validation.ts   # 表单验证
│   ├── format.ts       # 数据格式化
│   └── constants.ts    # 常量定义
└── router/             # 路由配置
    ├── index.ts        # 路由定义
    ├── users.ts        # 用户路由
    └── orders.ts       # 订单路由

5.2 性能优化实战

React 性能优化

// 1. 组件懒加载
const UsersPage = lazy(() => import('./pages/UsersPage'));
const OrdersPage = lazy(() => import('./pages/OrdersPage'));

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <Routes>
        <Route path="/users" element={<UsersPage />} />
        <Route path="/orders" element={<OrdersPage />} />
      </Routes>
    </Suspense>
  );
}

// 2. 组件记忆化
const UserListItem = memo(function UserListItem({ user }: { user: User }) {
  return (
    <div className="user-item">
      <h3>{user.name}</h3>
      <p>{user.email}</p>
    </div>
  );
});

// 3. 复杂计算缓存
const UserList = ({ users }: { users: User[] }) => {
  const filteredUsers = useMemo(() => {
    return users.filter(user => user.status === 'active');
  }, [users]);

  const sortedUsers = useMemo(() => {
    return filteredUsers.sort((a, b) => a.name.localeCompare(b.name));
  }, [filteredUsers]);

  return (
    <div>
      {sortedUsers.map(user => (
        <UserListItem key={user.id} user={user} />
      ))}
    </div>
  );
};

// 4. 事件处理器优化
const UserSearch = ({ onSearch }: { onSearch: (query: string) => void }) => {
  const debouncedSearch = useMemo(
    () => debounce(onSearch, 300),
    [onSearch]
  );

  return (
    <input
      type="text"
      placeholder="搜索用户..."
      onChange={(e) => debouncedSearch(e.target.value)}
    />
  );
};

TanStack 性能调优

// Query 缓存策略优化
const useOptimizedUserQuery = (userId: string) => {
  return useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
    staleTime: 2 * 60 * 1000,  // 2分钟内认为数据新鲜
    cacheTime: 10 * 60 * 1000, // 10分钟后清理缓存
    refetchOnWindowFocus: false, // 窗口聚焦时不自动刷新
    refetchOnReconnect: true,   // 网络重连时刷新
    select: (data) => {
      // 数据转换，只在内存中进行
      return {
        ...data,
        fullName: `${data.firstName} ${data.lastName}`,
        isActive: data.status === 'active',
      };
    },
  });
};

// Table 虚拟化（处理大数据量）
import { useVirtualizer } from '@tanstack/react-virtual';

function VirtualizedUserTable({ users }: { users: User[] }) {
  const table = useReactTable({
    data: users,
    columns: userColumns,
    getCoreRowModel: getCoreRowModel(),
  });

  const parentRef = useRef<HTMLDivElement>(null);

  const virtualizer = useVirtualizer({
    count: table.getRowModel().rows.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 50, // 每行高度
    overscan: 5, // 预渲染额外5行
  });

  return (
    <div ref={parentRef} className="virtual-table-container">
      <div style={{ height: virtualizer.getTotalSize(), position: 'relative' }}>
        {virtualizer.getVirtualItems().map((virtualItem) => {
          const row = table.getRowModel().rows[virtualItem.index];
          return (
            <div
              key={row.id}
              style={{
                position: 'absolute',
                top: 0,
                left: 0,
                width: '100%',
                height: `${virtualItem.size}px`,
                transform: `translateY(${virtualItem.start}px)`,
              }}
            >
              <TableRow row={row} />
            </div>
          );
        })}
      </div>
    </div>
  );
}

6. 阶段五：进阶与最佳实践 (2-3 周)

6.1 测试策略

// 组件单元测试
import { render, screen, fireEvent, waitFor } from '@testing-library/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { UserList } from './UserList';

describe('UserList', () => {
  let queryClient: QueryClient;

  beforeEach(() => {
    queryClient = new QueryClient({
      defaultOptions: {
        queries: { retry: false },
        mutations: { retry: false },
      },
    });
  });

  const renderWithQueryClient = (component: React.ReactElement) => {
    return render(
      <QueryClientProvider client={queryClient}>
        {component}
      </QueryClientProvider>
    );
  };

  test('displays loading state initially', () => {
    renderWithQueryClient(<UserList />);
    expect(screen.getByText('Loading...')).toBeInTheDocument();
  });

  test('displays users after successful fetch', async () => {
    const mockUsers = [
      { id: 1, name: 'John Doe', email: '[email protected]' },
      { id: 2, name: 'Jane Smith', email: '[email protected]' },
    ];

    jest.spyOn(api, 'fetchUsers').mockResolvedValue(mockUsers);

    renderWithQueryClient(<UserList />);

    await waitFor(() => {
      expect(screen.getByText('John Doe')).toBeInTheDocument();
      expect(screen.getByText('Jane Smith')).toBeInTheDocument();
    });
  });
});

// Hook测试
import { renderHook, waitFor } from '@testing-library/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { useUsers } from './useUsers';

const wrapper = ({ children }: { children: React.ReactNode }) => (
  <QueryClientProvider client={new QueryClient()}>
    {children}
  </QueryClientProvider>
);

test('useUsers returns users data', async () => {
  const mockUsers = [
    { id: 1, name: 'Test User' },
  ];

  jest.spyOn(api, 'fetchUsers').mockResolvedValue(mockUsers);

  const { result } = renderHook(() => useUsers(), { wrapper });

  expect(result.current.isLoading).toBe(true);

  await waitFor(() => {
    expect(result.current.data).toEqual(mockUsers);
    expect(result.current.isLoading).toBe(false);
  });
});

6.2 错误处理最佳实践

// 全局错误边界
class ErrorBoundary extends React.Component<
  { children: React.ReactNode },
  { hasError: boolean; error?: Error }
> {
  constructor(props: { children: React.ReactNode }) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError(error: Error) {
    return { hasError: true, error };
  }

  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
    console.error('Error caught by boundary:', error, errorInfo);
    // 发送错误报告到监控服务
    errorReporting.captureException(error, {
      extra: errorInfo,
    });
  }

  render() {
    if (this.state.hasError) {
      return (
        <div className="error-fallback">
          <h2>出错了</h2>
          <p>应用遇到了一个错误，请刷新页面重试</p>
          <button onClick={() => window.location.reload()}>
            刷新页面
          </button>
        </div>
      );
    }

    return this.props.children;
  }
}

// Query 错误处理
const useUsersWithErrorHandling = () => {
  return useQuery({
    queryKey: ['users'],
    queryFn: fetchUsers,
    retry: (failureCount, error) => {
      // 网络错误重试，其他错误不重试
      if (error.code === 'NETWORK_ERROR') {
        return failureCount < 3;
      }
      return false;
    },
    onError: (error) => {
      // 显示用户友好的错误信息
      if (error.code === 'UNAUTHORIZED') {
        showToast('请先登录', 'error');
      } else if (error.code === 'FORBIDDEN') {
        showToast('没有权限访问', 'error');
      } else {
        showToast('获取用户列表失败', 'error');
      }
    },
  });
};

7. 学习建议与资源推荐

7.1 学习策略

循序渐进的路径

1. 第1-2周：JavaScript/TypeScript基础强化
2. 第3-4周：React生态系统和Hooks
3. 第5-6周：TanStack Query深度学习
4. 第7周：TanStack Table和Form
5. 第8周：TanStack Router
6. 第9-12周：项目实战和优化

对比学习方法

充分利用你的Python背景：

• Python的装饰器 ↔ React的Hooks
• Django的ORM ↔ TanStack Query的缓存
• Django的路由 ↔ TanStack Router
• Django Forms ↔ TanStack Form

7.2 实践建议

项目驱动学习

• 每学完一个概念，立即在小项目中应用
• 构建一个完整的SaaS管理后台
• 参与开源项目贡献代码

代码阅读

• 阅读TanStack源码理解设计理念
• 研究优秀项目的架构设计
• 学习TypeScript类型系统的最佳实践

7.3 推荐资源

官方文档

• TanStack 官网 - 最权威的学习资源
• React 官方文档 - React最新特性
• TypeScript Handbook - TypeScript深度指南

实践平台

• StackBlitz - 在线开发环境，无需本地配置
• CodeSandbox - 快速原型开发
• Frontend Mentor - 实战项目练习

社区资源

• GitHub - 源码学习和问题反馈
• Discord - 官方社区交流
• Twitter - 创始人动态和最新资讯

总结

从Python转向前端开发是一个充满机遇的转型。你的后端经验为你提供了：

1. 系统性思维：理解数据流、状态管理和架构设计
2. API经验：熟悉HTTP协议和数据处理
3. 类型意识：从Python类型提示到TypeScript的自然过渡

TanStack生态系统的工程化思维与你的后端背景高度契合。通过系统性的学习和实践，你将能够：

• 构建类型安全、高性能的现代前端应用
• 掌握React生态系统的最佳实践
• 理解前后端协作的设计模式
• 具备解决复杂前端问题的能力

记住，学习是一个持续的过程。保持好奇心，多动手实践，积极参与社区，你将在前端开发领域找到新的乐趣和成就感。