⚡

前端开发指南Skill frontend-dev-guidelines

提供前端开发的最佳实践和指南，专注于React/TypeScript应用程序，覆盖Suspense数据获取、懒加载、TanStack Router路由、MUI v7样式、性能优化等现代技术。适用于前端开发者创建高效、可维护的应用程序，关键词：前端开发、React、TypeScript、Suspense、懒加载、TanStack Query、MUI、性能优化。

前端开发 0 次安装 0 次浏览 更新于 3/15/2026

名称: 前端开发指南 描述: React/TypeScript应用程序的前端开发指南。现代模式包括Suspense、懒加载、useSuspenseQuery、带有features目录的文件组织、MUI v7样式、TanStack Router、性能优化和TypeScript最佳实践。在创建组件、页面、功能、获取数据、样式、路由或处理前端代码时使用。

前端开发指南

目的

现代React开发的全面指南，强调基于Suspense的数据获取、懒加载、正确的文件组织和性能优化。

何时使用此技能

  • 创建新组件或页面
  • 构建新功能
  • 使用TanStack Query获取数据
  • 使用TanStack Router设置路由
  • 使用MUI v7样式化组件
  • 性能优化
  • 组织前端代码
  • TypeScript最佳实践

快速开始

新组件清单

创建组件？遵循此清单：

  • [ ] 使用带有TypeScript的React.FC<Props>模式
  • [ ] 如果是重型组件，则懒加载：React.lazy(() => import())
  • [ ] 用<SuspenseLoader>包装以实现加载状态
  • [ ] 使用useSuspenseQuery进行数据获取
  • [ ] 导入别名：@/、~types、~components、~features
  • [ ] 样式：少于100行时内联，大于100行时单独文件
  • [ ] 使用useCallback用于传递给子组件的事件处理程序
  • [ ] 在底部进行默认导出
  • [ ] 不使用带有加载微调器的早期返回
  • [ ] 使用useMuiSnackbar进行用户通知

新功能清单

创建功能？设置此结构：

  • [ ] 创建features/{feature-name}/目录
  • [ ] 创建子目录：api/、components/、hooks/、helpers/、types/
  • [ ] 创建API服务文件：api/{feature}Api.ts
  • [ ] 在types/中设置TypeScript类型
  • [ ] 在routes/{feature-name}/index.tsx中创建路由
  • [ ] 懒加载功能组件
  • [ ] 使用Suspense边界
  • [ ] 从功能index.ts导出公共API

导入别名快速参考

别名 解析为 示例
@/ src/ import { apiClient } from '@/lib/apiClient'
~types src/types import type { User } from '~types/user'
~components src/components import { SuspenseLoader } from '~components/SuspenseLoader'
~features src/features import { authApi } from '~features/auth'

定义于：vite.config.ts 第180-185行

常见导入速查表

// React 和 懒加载
import React, { useState, useCallback, useMemo } from 'react';
const Heavy = React.lazy(() => import('./Heavy'));

// MUI 组件
import { Box, Paper, Typography, Button, Grid } from '@mui/material';
import type { SxProps, Theme } from '@mui/material';

// TanStack Query (Suspense)
import { useSuspenseQuery, useQueryClient } from '@tanstack/react-query';

// TanStack Router
import { createFileRoute } from '@tanstack/react-router';

// 项目组件
import { SuspenseLoader } from '~components/SuspenseLoader';

// 钩子
import { useAuth } from '@/hooks/useAuth';
import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';

// 类型
import type { Post } from '~types/post';

主题指南

🎨 组件模式

现代React组件使用：

  • React.FC<Props>以实现类型安全
  • React.lazy()用于代码拆分
  • SuspenseLoader用于加载状态
  • 命名常量 + 默认导出模式

关键概念：

  • 懒加载重型组件（DataGrid、图表、编辑器）
  • 始终将懒加载组件包装在Suspense中
  • 使用SuspenseLoader组件（带有淡入动画）
  • 组件结构：Props → Hooks → 处理程序 → 渲染 → 导出

📖 完整指南：resources/component-patterns.md

📊 数据获取

主要模式：useSuspenseQuery

  • 与Suspense边界一起使用
  • 缓存优先策略（在API之前检查网格缓存）
  • 替代isLoading检查
  • 使用泛型实现类型安全

API服务层：

  • 创建features/{feature}/api/{feature}Api.ts
  • 使用apiClient axios实例
  • 按功能集中方法
  • 路由格式：/form/route（非/api/form/route）

📖 完整指南：resources/data-fetching.md

📁 文件组织

features/ 与 components/：

  • features/：领域特定（帖子、评论、认证）
  • components/：真正可重用（SuspenseLoader、CustomAppBar）

功能子目录：

features/
  my-feature/
    api/          # API服务层
    components/   # 功能组件
    hooks/        # 自定义钩子
    helpers/      # 工具函数
    types/        # TypeScript类型

📖 完整指南：resources/file-organization.md

🎨 样式化

内联与分离：

  • <100行：内联 const styles: Record<string, SxProps<Theme>>

  • 100行：分离.styles.ts文件

主要方法：

  • 使用sx属性用于MUI组件
  • 使用SxProps<Theme>实现类型安全
  • 主题访问：(theme) => theme.palette.primary.main

MUI v7 网格：

<Grid size={{ xs: 12, md: 6 }}>  // ✅ v7语法
<Grid xs={12} md={6}>             // ❌ 旧语法

📖 完整指南：resources/styling-guide.md

🛣️ 路由

TanStack Router - 文件夹基础：

  • 目录：routes/my-route/index.tsx
  • 懒加载组件
  • 使用createFileRoute
  • 加载器中的面包屑数据

示例：

import { createFileRoute } from '@tanstack/react-router';
import { lazy } from 'react';

const MyPage = lazy(() => import('@/features/my-feature/components/MyPage'));

export const Route = createFileRoute('/my-route/')({
    component: MyPage,
    loader: () => ({ crumb: '我的路由' }),
});

📖 完整指南：resources/routing-guide.md

⏳ 加载和错误状态

关键规则：无早期返回

// ❌ 从不 - 导致布局偏移
if (isLoading) {
    return <LoadingSpinner />;
}

// ✅ 总是 - 一致布局
<SuspenseLoader>
    <Content />
</SuspenseLoader>

原因： 防止累积布局偏移（CLS），提供更好的用户体验

错误处理：

  • 使用useMuiSnackbar进行用户反馈
  • 从不使用react-toastify
  • TanStack Query onError回调

📖 完整指南：resources/loading-and-error-states.md

⚡ 性能

优化模式：

  • useMemo：昂贵的计算（过滤、排序、映射）
  • useCallback：传递给子组件的事件处理程序
  • React.memo：昂贵的组件
  • 防抖搜索（300-500毫秒）
  • 内存泄漏预防（在useEffect中清理）

📖 完整指南：resources/performance.md

📘 TypeScript

标准：

  • 严格模式，无any类型
  • 函数上的显式返回类型
  • 类型导入：import type { User } from '~types/user'
  • 带有JSDoc的组件prop接口

📖 完整指南：resources/typescript-standards.md

🔧 常见模式

涵盖主题：

  • 带有Zod验证的React Hook Form
  • DataGrid包装器合约
  • 对话框组件标准
  • 用于当前用户的useAuth钩子
  • 带有缓存无效化的变异模式

📖 完整指南：resources/common-patterns.md

📚 完整示例

完整工作示例：

  • 具有所有模式的现代组件
  • 完整功能结构
  • API服务层
  • 带有懒加载的路由
  • Suspense + useSuspenseQuery
  • 带有验证的表单

📖 完整指南：resources/complete-examples.md

导航指南

需要… 阅读此资源
创建组件 component-patterns.md
获取数据 data-fetching.md
组织文件/文件夹 file-organization.md
样式化组件 styling-guide.md
设置路由 routing-guide.md
处理加载/错误 loading-and-error-states.md
优化性能 performance.md
TypeScript类型 typescript-standards.md
表单/认证/DataGrid common-patterns.md
查看完整示例 complete-examples.md

核心原则

  1. 懒加载一切重型： 路由、DataGrid、图表、编辑器
  2. 使用Suspense进行加载： 使用SuspenseLoader，而不是早期返回
  3. useSuspenseQuery： 新代码的主要数据获取模式
  4. 功能组织： api/、components/、hooks/、helpers/子目录
  5. 基于大小的样式： <100行内联，>100行分离
  6. 导入别名： 使用@/、~types、~components、~features
  7. 无早期返回： 防止布局偏移
  8. useMuiSnackbar： 用于所有用户通知

快速参考：文件结构

src/
  features/
    my-feature/
      api/
        myFeatureApi.ts       # API服务
      components/
        MyFeature.tsx         # 主组件
        SubComponent.tsx      # 相关组件
      hooks/
        useMyFeature.ts       # 自定义钩子
        useSuspenseMyFeature.ts  # Suspense钩子
      helpers/
        myFeatureHelpers.ts   # 工具
      types/
        index.ts              # TypeScript类型
      index.ts                # 公共导出

  components/
    SuspenseLoader/
      SuspenseLoader.tsx      # 可重用加载器
    CustomAppBar/
      CustomAppBar.tsx        # 可重用应用栏

  routes/
    my-route/
      index.tsx               # 路由组件
      create/
        index.tsx             # 嵌套路由

现代组件模板（快速复制）

import React, { useState, useCallback } from 'react';
import { Box, Paper } from '@mui/material';
import { useSuspenseQuery } from '@tanstack/react-query';
import { featureApi } from '../api/featureApi';
import type { FeatureData } from '~types/feature';

interface MyComponentProps {
    id: number;
    onAction?: () => void;
}

export const MyComponent: React.FC<MyComponentProps> = ({ id, onAction }) => {
    const [state, setState] = useState<string>('');

    const { data } = useSuspenseQuery({
        queryKey: ['feature', id],
        queryFn: () => featureApi.getFeature(id),
    });

    const handleAction = useCallback(() => {
        setState('updated');
        onAction?.();
    }, [onAction]);

    return (
        <Box sx={{ p: 2 }}>
            <Paper sx={{ p: 3 }}>
                {/* 内容 */}
            </Paper>
        </Box>
    );
};

export default MyComponent;

完整示例见 resources/complete-examples.md

相关技能

  • 错误跟踪： 使用Sentry进行错误跟踪（也适用于前端）
  • 后端开发指南： 前端消费的后端API模式

技能状态： 模块化结构，具有渐进加载以实现最优上下文管理