frontend-engineer

前端工程师

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

使用场景

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

快速开始

新建组件检查清单

• 使用 React.FC<Props> TypeScript 模式
• 如果组件较重，则延迟加载：React.lazy(() => import())
• 使用 <SuspenseLoader> 包裹，以处理加载状态
• 使用 useSuspenseQuery 获取数据
• 使用导入别名：@/、~types、~components、~features
• 样式：少于 100 行时内联，超过 100 行时使用单独文件
• 对传递给子组件的事件处理函数使用 useCallback
• 在文件底部默认导出
• 不要通过提前返回加载指示器来处理加载状态
• 使用通知系统向用户提供反馈

新建功能检查清单

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

核心原则

1. 延迟加载所有较重的内容： 路由、DataGrid、图表、编辑器
2. 使用 Suspense 处理加载： 使用 SuspenseLoader，而非提前返回
3. useSuspenseQuery： 新代码的首选数据获取模式
4. 按功能组织代码： 使用 api/、components/、hooks/、helpers/ 子目录
5. 根据大小选择样式方式： 少于 100 行时内联，超过 100 行时单独存放
6. 使用导入别名： 使用 @/、~types、~components、~features
7. 不要提前返回： 避免布局偏移
8. 优先使用 TypeScript： 启用严格模式，不使用 any 类型

实现工作流

实现前端代码时：

• 检查是否存在现有工作流模式（先写规范、TDD 等），并遵循这些模式
• 确保代码通过 CI 检查（类型、测试、lint）后再提交
• 将相关更改与测试一起打包为原子提交

参考资料

详细指南请参阅：

• references/component-patterns.md - 现代 React 组件模式
• references/data-fetching.md - 基于 Suspense 的数据获取
• references/file-organization.md - 基于功能的代码组织
• references/styling-guide.md - 样式模式与最佳实践
• references/routing-guide.md - TanStack Router 模式
• references/performance.md - 性能优化
• references/typescript-standards.md - TypeScript 最佳实践