React 全家桶深度实战：Redux + Ant Design + Hooks 构建企业级中后台前端解决方案

pnpm create vite react-enterprise --template react-ts
cd react-enterprise
pnpm add @reduxjs/toolkit react-redux react-router-dom antd @ant-design/icons axios dayjs
pnpm add -D @types/node @types/react @types/react-dom eslint prettier

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
  css: {
    preprocessorOptions: {
      less: {
        javascriptEnabled: true,
        modifyVars: {
          '@primary-color': '#1890ff',
        },
      },
    },
  },
  server: {
    port: 3000,
    proxy: {
      '/api': {
        target: 'https://mock.example.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ''),
      },
    },
  },
});

// src/store/index.ts
import { configureStore } from '@reduxjs/toolkit';
import authReducer from './slices/authSlice';
import orderReducer from './slices/orderSlice';
import { api } from './services/api';

export const store = configureStore({
  reducer: {
    auth: authReducer,
    order: orderReducer,
    [api.reducerPath]: api.reducer,
  },
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware({
      serializableCheck: {
        ignoredActions: ['persist/PERSIST'],
      },
    }).concat(api.middleware),
});

export type RootState = ReturnType<typeof store.getState>;
export type AppDispatch = typeof store.dispatch;

// 带类型的 useDispatch 和 useSelector
import { useDispatch, useSelector } from 'react-redux';
export const useAppDispatch = () => useDispatch<AppDispatch>();
export const useAppSelector = <T>(selector: (state: RootState) => T) =>
  useSelector(selector);

// src/store/slices/authSlice.ts
import { createSlice, createAsyncThunk } from '@reduxjs/toolkit';
import axios from 'axios';

interface AuthState {
  token: string | null;
  user: { id: string; name: string; roles: string[] } | null;
  loading: boolean;
  error: string | null;
}

const initialState: AuthState = {
  token: localStorage.getItem('token'),
  user: null,
  loading: false,
  error: null,
};

export const login = createAsyncThunk(
  'auth/login',
  async (credentials: { username: string; password: string }) => {
    const response = await axios.post('/api/auth/login', credentials);
    // 假设返回 { token, user }
    return response.data;
  }
);

const authSlice = createSlice({
  name: 'auth',
  initialState,
  reducers: {
    logout(state) {
      state.token = null;
      state.user = null;
      localStorage.removeItem('token');
    },
    clearError(state) {
      state.error = null;
    },
  },
  extraReducers: (builder) => {
    builder
      .addCase(login.pending, (state) => {
        state.loading = true;
        state.error = null;
      })
      .addCase(login.fulfilled, (state, action) => {
        state.loading = false;
        state.token = action.payload.token;
        state.user = action.payload.user;
        localStorage.setItem('token', action.payload.token);
      })
      .addCase(login.rejected, (state, action) => {
        state.loading = false;
        state.error = action.error.message || '登录失败';
      });
  },
});

export const { logout, clearError } = authSlice.actions;
export default authSlice.reducer;

// src/store/slices/orderSlice.ts
import { createEntityAdapter, createSlice, createAsyncThunk } from '@reduxjs/toolkit';
import axios from 'axios';
import { RootState } from '..';

// 订单实体
interface Order {
  id: string;
  orderNo: string;
  customer: string;
  amount: number;
  status: 'pending' | 'shipped' | 'delivered' | 'cancelled';
  createdAt: string;
}

// 分页参数
interface FetchOrdersParams {
  page: number;
  pageSize: number;
  status?: string;
  keyword?: string;
}

// 适配器
const ordersAdapter = createEntityAdapter<Order>({
  selectId: (order) => order.id,
  sortComparer: (a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime(),
});

interface OrderState {
  ids: string[];
  entities: Record<string, Order>;
  total: number;
  page: number;
  pageSize: number;
  loading: boolean;
  error: string | null;
  selectedIds: string[];
}

const initialState = ordersAdapter.getInitialState<Omit<OrderState, 'ids' | 'entities'>>({
  total: 0,
  page: 1,
  pageSize: 10,
  loading: false,
  error: null,
  selectedIds: [],
});

// 异步 thunk
export const fetchOrders = createAsyncThunk(
  'order/fetchOrders',
  async (params: FetchOrdersParams) => {
    const response = await axios.get('/api/orders', { params });
    return {
      orders: response.data.items,
      total: response.data.total,
      page: params.page,
      pageSize: params.pageSize,
    };
  }
);

export const updateOrderStatus = createAsyncThunk(
  'order/updateStatus',
  async ({ id, status }: { id: string; status: Order['status'] }) => {
    const response = await axios.patch(`/api/orders/${id}/status`, { status });
    return response.data; // 返回更新后的订单
  }
);

const orderSlice = createSlice({
  name: 'order',
  initialState,
  reducers: {
    toggleSelect(state, action: { payload: string }) {
      const idx = state.selectedIds.indexOf(action.payload);
      if (idx > -1) state.selectedIds.splice(idx, 1);
      else state.selectedIds.push(action.payload);
    },
    clearSelection(state) {
      state.selectedIds = [];
    },
    setPage(state, action) {
      state.page = action.payload;
    },
    setPageSize(state, action) {
      state.pageSize = action.payload;
    },
  },
  extraReducers: (builder) => {
    builder
      .addCase(fetchOrders.pending, (state) => {
        state.loading = true;
        state.error = null;
      })
      .addCase(fetchOrders.fulfilled, (state, action) => {
        state.loading = false;
        const { orders, total, page, pageSize } = action.payload;
        ordersAdapter.setAll(state, orders);
        state.total = total;
        state.page = page;
        state.pageSize = pageSize;
      })
      .addCase(fetchOrders.rejected, (state, action) => {
        state.loading = false;
        state.error = action.error.message || '加载失败';
      })
      .addCase(updateOrderStatus.fulfilled, (state, action) => {
        const updated = action.payload;
        ordersAdapter.updateOne(state, {
          id: updated.id,
          changes: { status: updated.status },
        });
      });
  },
});

export const {
  selectAll: selectAllOrders,
  selectById: selectOrderById,
  selectIds: selectOrderIds,
  selectTotal: selectOrderTotal,
} = ordersAdapter.getSelectors((state: RootState) => state.order);

export const { toggleSelect, clearSelection, setPage, setPageSize } = orderSlice.actions;
export default orderSlice.reducer;

// src/store/services/api.ts
import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react';

export const api = createApi({
  reducerPath: 'api',
  baseQuery: fetchBaseQuery({
    baseUrl: import.meta.env.VITE_API_BASE,
    prepareHeaders: (headers, { getState }) => {
      const token = (getState() as RootState).auth.token;
      if (token) headers.set('Authorization', `Bearer ${token}`);
      return headers;
    },
  }),
  tagTypes: ['Order', 'Stats'],
  endpoints: (builder) => ({
    getOrderStats: builder.query<{ total: number; pending: number; shipped: number }, void>({
      query: () => '/orders/stats',
      providesTags: ['Stats'],
    }),
    // 变更后自动重新获取统计
    updateOrder: builder.mutation<Order, Partial<Order>>({
      query: (body) => ({
        url: `/orders/${body.id}`,
        method: 'PATCH',
        body,
      }),
      invalidatesTags: ['Stats', 'Order'],
    }),
  }),
});

export const { useGetOrderStatsQuery, useUpdateOrderMutation } = api;

// src/App.tsx
import { ConfigProvider, App as AntApp } from 'antd';
import zhCN from 'antd/locale/zh_CN';
import { useSelector } from 'react-redux';
import { RootState } from './store';
import { RouterProvider } from 'react-router-dom';
import { router } from './router';

function App() {
  const { themeMode } = useSelector((state: RootState) => state.settings);

  return (
    <ConfigProvider
      locale={zhCN}
      theme={{
        token: {
          colorPrimary: '#1890ff',
          borderRadius: 6,
          fontSize: 14,
        },
        components: {
          Table: {
            headerBg: '#fafafa',
            rowHoverBg: '#f0f7ff',
          },
          Modal: {
            titleFontSize: 18,
          },
        },
        algorithm: themeMode === 'dark' ? darkAlgorithm : defaultAlgorithm,
      }}
    >
      <AntApp>
        <RouterProvider router={router} />
      </AntApp>
    </ConfigProvider>
  );
}

// src/components/SearchTable/index.tsx
import React, { useEffect, useState } from 'react';
import { Form, Input, Button, Table, Space, Select, Row, Col, Spin } from 'antd';
import { ReloadOutlined, SearchOutlined } from '@ant-design/icons';
import type { ColumnsType, TablePaginationConfig } from 'antd/es/table';

interface SearchField {
  name: string;
  label: string;
  type: 'input' | 'select' | 'dateRange';
  options?: { label: string; value: any }[];
  placeholder?: string;
}

interface SearchTableProps<T> {
  columns: ColumnsType<T>;
  fetchData: (params: any) => Promise<{ list: T[]; total: number }>;
  searchFields?: SearchField[];
  rowKey?: string;
  extraActions?: React.ReactNode;
}

export function SearchTable<T extends { id?: string }>({
  columns,
  fetchData,
  searchFields = [],
  rowKey = 'id',
  extraActions,
}: SearchTableProps<T>) {
  const [form] = Form.useForm();
  const [data, setData] = useState<T[]>([]);
  const [loading, setLoading] = useState(false);
  const [pagination, setPagination] = useState({ current: 1, pageSize: 10, total: 0 });

  const loadData = async (params: any = {}) => {
    setLoading(true);
    try {
      const res = await fetchData({
        page: pagination.current,
        pageSize: pagination.pageSize,
        ...params,
      });
      setData(res.list);
      setPagination((prev) => ({ ...prev, total: res.total }));
    } catch (error) {
      // antd message 全局提示
    } finally {
      setLoading(false);
    }
  };

  useEffect(() => {
    loadData();
  }, [pagination.current, pagination.pageSize]);

  const handleSearch = () => {
    const values = form.getFieldsValue();
    // 过滤空值
    const filtered = Object.fromEntries(
      Object.entries(values).filter(([_, v]) => v !== undefined && v !== '')
    );
    setPagination((prev) => ({ ...prev, current: 1 }));
    loadData({ ...filtered, page: 1, pageSize: pagination.pageSize });
  };

  const handleReset = () => {
    form.resetFields();
    setPagination((prev) => ({ ...prev, current: 1 }));
    loadData({ page: 1, pageSize: pagination.pageSize });
  };

  const handleTableChange = (paginationConfig: TablePaginationConfig) => {
    setPagination({
      current: paginationConfig.current || 1,
      pageSize: paginationConfig.pageSize || 10,
      total: pagination.total,
    });
  };

  return (
    <div className="search-table">
      {searchFields.length > 0 && (
        <Form form={form} layout="inline" style={{ marginBottom: 24 }}>
          <Row gutter={[16, 16]} style={{ width: '100%' }}>
            {searchFields.map((field) => (
              <Col key={field.name} span={6}>
                <Form.Item name={field.name} label={field.label}>
                  {field.type === 'input' && <Input placeholder={field.placeholder} allowClear />}
                  {field.type === 'select' && (
                    <Select placeholder={field.placeholder} options={field.options} allowClear />
                  )}
                </Form.Item>
              </Col>
            ))}
            <Col span={6} style={{ textAlign: 'right' }}>
              <Space>
                <Button icon={<SearchOutlined />} type="primary" onClick={handleSearch}>
                  查询
                </Button>
                <Button icon={<ReloadOutlined />} onClick={handleReset}>
                  重置
                </Button>
                {extraActions}
              </Space>
            </Col>
          </Row>
        </Form>
      )}
      <Spin spinning={loading}>
        <Table
          rowKey={rowKey}
          columns={columns}
          dataSource={data}
          pagination={pagination}
          onChange={handleTableChange}
          scroll={{ x: 'max-content' }}
        />
      </Spin>
    </div>
  );
}

// src/hooks/useAuth.ts
import { useCallback, useMemo } from 'react';
import { useAppDispatch, useAppSelector } from '@/store';
import { login as loginAction, logout as logoutAction, clearError } from '@/store/slices/authSlice';

export const useAuth = () => {
  const dispatch = useAppDispatch();
  const { token, user, loading, error } = useAppSelector((state) => state.auth);

  const login = useCallback(
    async (username: string, password: string) => {
      const result = await dispatch(loginAction({ username, password }));
      if (loginAction.fulfilled.match(result)) {
        return { success: true };
      }
      return { success: false, error: result.error?.message };
    },
    [dispatch]
  );

  const logout = useCallback(() => {
    dispatch(logoutAction());
  }, [dispatch]);

  const hasRole = useCallback(
    (role: string) => {
      return user?.roles?.includes(role) ?? false;
    },
    [user]
  );

  const isAuthenticated = useMemo(() => !!token, [token]);

  return {
    user,
    token,
    loading,
    error,
    isAuthenticated,
    login,
    logout,
    hasRole,
    clearError: () => dispatch(clearError()),
  };
};

// src/hooks/usePagination.ts
import { useState, useCallback } from 'react';

interface PaginationOptions {
  initialPage?: number;
  initialPageSize?: number;
  total?: number;
}

export function usePagination(options: PaginationOptions = {}) {
  const { initialPage = 1, initialPageSize = 10, total = 0 } = options;
  const [page, setPage] = useState(initialPage);
  const [pageSize, setPageSize] = useState(initialPageSize);

  const reset = useCallback(() => {
    setPage(initialPage);
    setPageSize(initialPageSize);
  }, [initialPage, initialPageSize]);

  const paginationProps = {
    current: page,
    pageSize,
    total,
    onChange: (p: number) => setPage(p),
    onShowSizeChange: (_: number, size: number) => {
      setPageSize(size);
      setPage(1);
    },
    showSizeChanger: true,
    showQuickJumper: true,
  };

  return { page, pageSize, setPage, setPageSize, reset, paginationProps };
}

// src/hooks/useRequest.ts
import { useState, useCallback } from 'react';

export function useRequest<T, P extends any[]>(
  fn: (...args: P) => Promise<T>,
  options?: { onSuccess?: (data: T) => void; onError?: (err: any) => void }
) {
  const [data, setData] = useState<T | null>(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<any>(null);

  const run = useCallback(
    async (...args: P) => {
      setLoading(true);
      setError(null);
      try {
        const result = await fn(...args);
        setData(result);
        options?.onSuccess?.(result);
        return result;
      } catch (err) {
        setError(err);
        options?.onError?.(err);
        throw err;
      } finally {
        setLoading(false);
      }
    },
    [fn, options]
  );

  return { data, loading, error, run, setData };
}

// src/pages/OrderList/index.tsx
import React, { useMemo } from 'react';
import { Card, Tag, Button, Space, Modal, message, Typography } from 'antd';
import { CheckCircleOutlined, CloseCircleOutlined, EyeOutlined } from '@ant-design/icons';
import { SearchTable } from '@/components/SearchTable';
import { useAppDispatch, useAppSelector } from '@/store';
import { fetchOrders, updateOrderStatus, toggleSelect, clearSelection } from '@/store/slices/orderSlice';
import { useGetOrderStatsQuery } from '@/store/services/api';
import { useAuth } from '@/hooks/useAuth';
import type { ColumnsType } from 'antd/es/table';

const statusMap = {
  pending: { color: 'gold', text: '待发货' },
  shipped: { color: 'blue', text: '运输中' },
  delivered: { color: 'green', text: '已送达' },
  cancelled: { color: 'red', text: '已取消' },
};

export default function OrderList() {
  const dispatch = useAppDispatch();
  const { hasRole } = useAuth();
  const { selectedIds } = useAppSelector((state) => state.order);
  const { data: stats, refetch: refetchStats } = useGetOrderStatsQuery();

  // 封装 fetch 函数供 SearchTable 调用
  const fetchOrdersWrapper = async (params: any) => {
    const result = await dispatch(fetchOrders(params)).unwrap();
    return { list: result.orders, total: result.total };
  };

  // 状态变更操作
  const handleStatusChange = (id: string, newStatus: string) => {
    Modal.confirm({
      title: '确认修改订单状态',
      content: `将订单状态变更为“${statusMap[newStatus].text}”？`,
      onOk: async () => {
        await dispatch(updateOrderStatus({ id, status: newStatus })).unwrap();
        message.success('更新成功');
        refetchStats(); // 刷新统计
      },
    });
  };

  // 批量操作
  const handleBatchUpdate = (status: string) => {
    if (selectedIds.length === 0) {
      message.warning('请先选择订单');
      return;
    }
    Modal.confirm({
      title: `批量更新 ${selectedIds.length} 个订单`,
      content: `确认全部变更为“${statusMap[status].text}”？`,
      onOk: async () => {
        // 并行执行
        await Promise.all(
          selectedIds.map((id) =>
            dispatch(updateOrderStatus({ id, status })).unwrap()
          )
        );
        message.success('批量更新成功');
        dispatch(clearSelection());
        refetchStats();
      },
    });
  };

  const columns: ColumnsType<any> = useMemo(
    () => [
      {
        title: '订单号',
        dataIndex: 'orderNo',
        key: 'orderNo',
        render: (text) => <Typography.Link>{text}</Typography.Link>,
      },
      {
        title: '客户',
        dataIndex: 'customer',
        key: 'customer',
      },
      {
        title: '金额',
        dataIndex: 'amount',
        key: 'amount',
        render: (val) => `¥${val.toFixed(2)}`,
      },
      {
        title: '状态',
        dataIndex: 'status',
        key: 'status',
        render: (status: keyof typeof statusMap) => (
          <Tag color={statusMap[status].color}>{statusMap[status].text}</Tag>
        ),
      },
      {
        title: '创建时间',
        dataIndex: 'createdAt',
        key: 'createdAt',
        render: (val) => new Date(val).toLocaleString('zh-CN'),
      },
      {
        title: '操作',
        key: 'actions',
        fixed: 'right',
        width: 180,
        render: (_, record) => (
          <Space>
            <Button
              type="link"
              icon={<EyeOutlined />}
              onClick={() => {/* 跳转详情 */}}
            >
              查看
            </Button>
            {hasRole('admin') && record.status !== 'delivered' && record.status !== 'cancelled' && (
              <Button
                type="link"
                onClick={() => handleStatusChange(record.id, 'delivered')}
              >
                标记送达
              </Button>
            )}
          </Space>
        ),
      },
    ],
    [hasRole]
  );

  const searchFields = [
    { name: 'keyword', label: '关键词', type: 'input', placeholder: '订单号/客户' },
    {
      name: 'status',
      label: '状态',
      type: 'select',
      options: Object.entries(statusMap).map(([k, v]) => ({ label: v.text, value: k })),
    },
  ];

  return (
    <div>
      {/* 统计卡片 */}
      <Space direction="horizontal" style={{ marginBottom: 16, width: '100%' }} wrap>
        <Card size="small" style={{ flex: 1 }}>
          <StatItem label="总订单" value={stats?.total ?? 0} />
        </Card>
        <Card size="small" style={{ flex: 1 }}>
          <StatItem label="待发货" value={stats?.pending ?? 0} color="gold" />
        </Card>
        <Card size="small" style={{ flex: 1 }}>
          <StatItem label="运输中" value={stats?.shipped ?? 0} color="blue" />
        </Card>
        <Card size="small" style={{ flex: 1 }}>
          <StatItem label="已送达" value={stats?.delivered ?? 0} color="green" />
        </Card>
      </Space>

      {/* 批量操作栏 */}
      {selectedIds.length > 0 && (
        <div style={{ marginBottom: 16, background: '#f6f8fa', padding: 12, borderRadius: 6 }}>
          <Space>
            <span>已选 {selectedIds.length} 项</span>
            <Button type="primary" size="small" onClick={() => handleBatchUpdate('delivered')}>
              批量标记送达
            </Button>
            <Button size="small" onClick={() => dispatch(clearSelection())}>
              取消选择
            </Button>
          </Space>
        </div>
      )}

      <SearchTable
        columns={columns}
        fetchData={fetchOrdersWrapper}
        searchFields={searchFields}
        rowKey="id"
        extraActions={
          <Button
            type="default"
            icon={<CheckCircleOutlined />}
            onClick={() => handleBatchUpdate('delivered')}
          >
            批量操作
          </Button>
        }
      />
    </div>
  );
}

// 统计卡片子组件
const StatItem = ({ label, value, color }: { label: string; value: number; color?: string }) => (
  <div style={{ textAlign: 'center' }}>
    <div style={{ fontSize: 14, color: '#888' }}>{label}</div>
    <div style={{ fontSize: 24, fontWeight: 600, color: color || '#1890ff' }}>{value}</div>
  </div>
);

// src/router/index.tsx
import { createBrowserRouter, Navigate } from 'react-router-dom';
import Layout from '@/layouts/MainLayout';
import Login from '@/pages/Login';
import OrderList from '@/pages/OrderList';
import Dashboard from '@/pages/Dashboard';
import { AuthGuard } from '@/components/AuthGuard';

export const router = createBrowserRouter([
  {
    path: '/login',
    element: <Login />,
  },
  {
    path: '/',
    element: <AuthGuard><Layout /></AuthGuard>,
    children: [
      { index: true, element: <Navigate to="/dashboard" /> },
      { path: 'dashboard', element: <Dashboard /> },
      { path: 'orders', element: <OrderList /> },
      // 其他路由...
    ],
  },
  { path: '*', element: <Navigate to="/" /> },
]);

// src/components/AuthGuard/index.tsx
import { useEffect } from 'react';
import { useNavigate, useLocation } from 'react-router-dom';
import { useAuth } from '@/hooks/useAuth';
import { Spin } from 'antd';

export const AuthGuard = ({ children }: { children: JSX.Element }) => {
  const { isAuthenticated, loading } = useAuth();
  const navigate = useNavigate();
  const location = useLocation();

  useEffect(() => {
    if (!loading && !isAuthenticated) {
      navigate('/login', { state: { from: location.pathname }, replace: true });
    }
  }, [isAuthenticated, loading, navigate, location]);

  if (loading) {
    return (
      <div style={{ display: 'flex', justifyContent: 'center', marginTop: 100 }}>
        <Spin size="large" tip="验证权限..." />
      </div>
    );
  }

  return isAuthenticated ? children : null;
};

const fetchOrdersWrapper = useCallback(async (params: any) => {
  const result = await dispatch(fetchOrders(params)).unwrap();
  return { list: result.orders, total: result.total };
}, [dispatch]);

<Table
  virtual
  scroll={{ x: 1200, y: 600 }}
  pagination={{ ...pagination, showSizeChanger: true }}
/>

// 在 orderSlice 外定义
export const selectFilteredOrders = createSelector(
  [selectAllOrders, (state: RootState) => state.order.selectedIds],
  (orders, selectedIds) => orders.map(o => ({ ...o, checked: selectedIds.includes(o.id) }))
);

const OrderList = lazy(() => import('@/pages/OrderList'));
const Dashboard = lazy(() => import('@/pages/Dashboard'));

// 在 router 中配合 Suspense
element: (
  <Suspense fallback={<Spin fullscreen />}>
    <AuthGuard><Layout /></AuthGuard>
  </Suspense>
)

// src/store/index.ts 扩展
import { persistStore, persistReducer } from 'redux-persist';
import storage from 'redux-persist/lib/storage';

const persistConfig = {
  key: 'root',
  storage,
  whitelist: ['auth', 'settings'],
};

const persistedReducer = persistReducer(persistConfig, rootReducer);
export const store = configureStore({
  reducer: persistedReducer,
  // ...
});
export const persistor = persistStore(store);

src/
├── store/          # Redux 配置与 slices
├── hooks/          # 自定义 hooks
├── components/     # 通用组件 (SearchTable, AuthGuard)
├── pages/          # 页面视图
├── layouts/        # 布局
├── router/         # 路由配置
├── services/       # API 定义 (RTK Query)
└── utils/          # 工具函数