frontend-dev-guidelines

前端开发指南

目的

全面介绍现代 React 开发，重点涵盖基于 Suspense 的数据获取、延迟加载、合理的文件组织和性能优化。

适用于 React 18 + TypeScript + MUI v7 + TanStack Router/Query。技术栈不同？请调整相关原则，并参阅仓库根目录中的 CLAUDE_INTEGRATION_GUIDE.md。

何时使用此技能

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

---

快速入门

新建组件检查清单

要创建组件？请按照此清单操作：

• 使用 React.FC<Props> TypeScript 模式
• 如果组件较重，则延迟加载：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 & Lazy Loading
import React, { useState, useCallback, useMemo } from 'react';
const Heavy = React.lazy(() => import('./Heavy'));

// MUI Components
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';

// Project Components
import { SuspenseLoader } from '~components/SuspenseLoader';

// Hooks
import { useAuth } from '@/hooks/useAuth';
import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';

// Types
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 service layer
    components/   # Feature components
    hooks/        # Custom hooks
    helpers/      # Utility functions
    types/        # TypeScript types

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

---

🎨 样式

内联还是独立：

• 少于 100 行：内联 const styles: Record<string, SxProps<Theme>>
• 多于 100 行：使用独立的 .styles.ts 文件

首选方式：

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

MUI v7 Grid：

<Grid size={{ xs: 12, md: 6 }}>  // ✅ v7 syntax
<Grid xs={12} md={6}>             // ❌ Old syntax

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

---

🛣️ 路由

TanStack Router——基于文件夹：

• 目录：routes/my-route/index.tsx
• 延迟加载组件
• 使用 createFileRoute
• 在 loader 中设置面包屑数据

示例：

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: 'My Route' }),
});

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

---

⏳ 加载与错误状态

关键规则：禁止提前返回

// ❌ NEVER - Causes layout shift
if (isLoading) {
    return <LoadingSpinner />;
}

// ✅ ALWAYS - Consistent layout
<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

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

---

🔧 常见模式

涵盖主题：

• 使用 Zod 验证的 React Hook Form
• DataGrid 包装器约定
• Dialog 组件规范
• 用于获取当前用户的 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
表单/Auth/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 service
      components/
        MyFeature.tsx         # Main component
        SubComponent.tsx      # Related components
      hooks/
        useMyFeature.ts       # Custom hooks
        useSuspenseMyFeature.ts  # Suspense hooks
      helpers/
        myFeatureHelpers.ts   # Utilities
      types/
        index.ts              # TypeScript types
      index.ts                # Public exports

  components/
    SuspenseLoader/
      SuspenseLoader.tsx      # Reusable loader
    CustomAppBar/
      CustomAppBar.tsx        # Reusable app bar

  routes/
    my-route/
      index.tsx               # Route component
      create/
        index.tsx             # Nested route

---

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

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 }}>
                {/* Content */}
            </Paper>
        </Box>
    );
};

export default MyComponent;

完整示例请参阅 resources/complete-examples.md

---

相关技能

• error-tracking：使用 Sentry 进行错误追踪（也适用于前端）
• backend-dev-guidelines：前端使用的后端 API 模式

---

技能状态：采用模块化结构并渐进式加载，以优化上下文管理