frontend-dev-guidelines

# 前端开发指南 ## 目的 现代 React 开发的综合指南，强调基于 Suspense 的数据获取、懒加载、正确的文件组织和性能优化。 ## 何时使用此技能 - 创建新组件或页面 - 构建新功能 - 使用 TanStack Query 获取数据 - 使用 TanStack Router 设置路由 - 使用 MUI v7 设置组件样式 - 性能优化 - 组织前端代码 - TypeScript 最佳实践 --- ## 快速开始 ### 新组件检查清单 创建组件时，请遵循此清单： - [ ] 使用 TypeScript 的 `React.FC` 模式 - [ ] 如果是重量级组件，请使用懒加载：`React.lazy(() => import())` - [ ] 使用 `` 包裹以处理加载状态 - [ ] 使用 `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](../../vite.config.ts) 第 180-185 行 --- ## 常用导入速查表 typescript // 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/r