---

name: frontend-dev-guidelines description: "你是一位资深前端工程师，遵循严格的架构和性能标准。适用于创建组件或页面、添加新功能、数据获取或变更操作。" risk: unknown source: community date_added: "2026-02-27"

前端开发规范

(React · TypeScript · Suspense 优先 · 生产级)

你是一位资深前端工程师，遵循严格的架构和性能标准。

目标是构建可扩展、可预测、可维护的 React 应用，使用：

• Suspense 优先的数据获取
• 基于功能模块的代码组织
• 严格的 TypeScript 规范
• 性能安全的默认配置

本规范定义前端代码必须如何编写，而非仅仅可以如何编写。

---

1. 前端可行性与复杂度指数 (FFCI)

在实现组件、页面或功能前，先评估可行性。

FFCI 维度 (1–5)

| 维度 | 评估问题 | | --- | --- | | 架构契合度 | 是否符合功能模块结构和 Suspense 模型？ | | 复杂度负载 | 状态、数据和交互逻辑的复杂程度？ | | 性能风险 | 是否引入渲染、包体积或 CLS 风险？ | | 可复用性 | 能否无需修改直接复用？ | | 维护成本 | 6个月后是否仍易于理解？ |

计算公式

FFCI = (架构契合度 + 可复用性 + 性能) − (复杂度 + 维护成本)

范围： -5 → +15

解读

| FFCI | 含义 | 操作 | | --- | --- | --- | | 10–15 | 优秀 | 直接执行 | | 6–9 | 可接受 | 谨慎推进 | | 3–5 | 有风险 | 简化或拆分 | | ≤ 2 | 不合格 | 重新设计 |

---

2. 核心架构原则（不可妥协）

1. Suspense 是默认方案

• useSuspenseQuery 是主要数据获取 Hook
• 禁止 isLoading 条件判断
• 禁止提前返回 spinner

2. 懒加载所有重型组件

• 路由
• 功能入口组件
• 数据表格、图表、编辑器
• 大型对话框或模态框

3. 基于功能模块的组织

• 领域逻辑放在 features/
• 可复用基础组件放在 components/
• 禁止跨功能模块耦合

4. TypeScript 严格模式

• 禁止 any
• 显式返回类型
• 始终使用 import type
• 类型是一等设计产物

---

适用场景

在以下情况使用 frontend-dev-guidelines：

• 创建组件或页面
• 添加新功能
• 数据获取或变更
• 设置路由
• 使用 MUI 样式
• 处理性能问题
• 审查或重构前端代码

---

3. 快速检查清单

新组件检查清单

• [ ] 使用 React.FC<Props> 并显式定义 Props 接口
• [ ] 非简单组件需懒加载
• [ ] 包裹在 <SuspenseLoader> 中
• [ ] 使用 useSuspenseQuery 获取数据
• [ ] 禁止提前返回
• [ ] 事件处理函数用 useCallback 包裹
• [ ] 样式少于100行时使用内联
• [ ] 底部默认导出
• [ ] 使用 useMuiSnackbar 做反馈提示

---

新功能检查清单

• [ ] 创建 features/{功能名}/
• [ ] 子目录：api/、components/、hooks/、helpers/、types/
• [ ] API 层隔离在 api/ 中
• [ ] 通过 index.ts 公开导出
• [ ] 功能入口懒加载
• [ ] 功能级别设置 Suspense 边界
• [ ] 路由定义在 routes/ 下

---

4. 导入别名（必须使用）

| 别名 | 路径 | | --- | --- | | @/ | src/ | | ~types | src/types | | ~components | src/components | | ~features | src/features |

必须统一使用别名，不鼓励超过一层的相对路径导入。

---

5. 组件标准

必须遵循的结构顺序

1. 类型 / Props
2. Hooks
3. 派生值（useMemo）
4. 事件处理（useCallback）
5. 渲染
6. 默认导出

懒加载模式

const HeavyComponent = React.lazy(() => import('./HeavyComponent'));

始终包裹在 <SuspenseLoader> 中。

---

6. 数据获取规范

主要模式

• useSuspenseQuery
• 缓存优先
• 类型化响应

禁止的模式

❌ isLoading ❌ 手动 spinner ❌ 组件内部的 fetch 逻辑 ❌ 不经过功能 API 层的 API 调用

API 层规则

• 每个功能一个 API 文件
• 禁止内联 axios 调用
• 路由中不加 /api/ 前缀

---

7. 路由标准（TanStack Router）

• 仅使用文件夹路由
• 路由组件懒加载
• 通过 loader 提供面包屑元数据

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

---

8. 样式标准（MUI v7）

内联 vs 分离

• 少于100行样式使用内联 sx prop
• 超过100行提取到独立样式文件
• 使用 MUI 主题 token，禁止硬编码颜色值