frontend-dev-guidelines

前端开发指南

（React · TypeScript · 面向 Suspense 的示例）

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

你的目标是使用以下方式构建可扩展、可预测且易于维护的 React 应用：

• 优先使用 Suspense 获取数据
• 基于功能组织代码
• 严格遵循 TypeScript 规范
• 默认采用安全的性能设置

这些约定适用于示例性的 MUI/TanStack 应用。现有项目要求和用户指定的范围优先；不要强行迁移技术栈。

---

1. 前端可行性与复杂度指数（FFCI）

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

FFCI 维度（1–5）

维度	问题
架构契合度	是否符合基于功能的结构和 Suspense 模型？
复杂度负担	状态、数据和交互逻辑有多复杂？
性能安全性	是否会带来渲染、打包体积或 CLS 风险？
可复用性	无需修改即可复用吗？
维护成本	6 个月后理解起来会有多困难？

评分公式

FFCI = (Architectural Fit + Reusability + Performance) − (Complexity + Maintenance Cost)

范围： -7 → +13

说明

FFCI	含义	操作
10–13	优秀	继续
6–9	可接受	谨慎继续
3–5	有风险	简化或拆分
≤ 2	较差	重新设计

---

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

1. 默认使用 Suspense

• useSuspenseQuery 是主要的数据获取 Hook
• 不使用 isLoading 条件判断
• 不提前返回加载指示器

2. 对任何大型内容进行懒加载

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

3. 基于功能组织代码

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

4. 严格使用 TypeScript

• 不使用 any
• 显式声明返回类型
• 始终使用 import type
• 将类型视为一等设计工件

---

适用场景

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

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

---

3. 快速入门检查清单

新组件检查清单

• 使用 React.FC<Props> 并显式定义 props 接口
• 如组件并非简单组件，则进行懒加载
• 使用 <SuspenseLoader> 包装
• 使用 useSuspenseQuery 获取数据
• 不提前返回
• 使用 useCallback 包装处理函数
• 样式少于 100 行时内联编写
• 在底部默认导出
• 使用 useMuiSnackbar 提供反馈

---

新功能检查清单

• 创建 features/{feature-name}/
• 子目录：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 ❌ 手动显示加载动画 ❌ 在组件中编写获取数据的逻辑 ❌ 未通过功能 API 层发起 API 调用

API 层规则

• 每个功能对应一个 API 文件
• 不要内联调用 axios
• 路由中不要使用 /api/ 前缀

---

7. 路由规范（TanStack Router）

• 仅使用基于文件夹的路由
• 延迟加载路由组件
• 通过加载器提供面包屑元数据

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

---

8. 样式规范（MUI v7）

内联样式与独立样式

• <100 lines：内联使用 sx
• >100 lines：使用 {Component}.styles.ts

Grid 语法（仅限 v7）

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

主题访问必须始终确保类型安全。

---

9. 加载与错误处理

绝对规则

❌ 绝不提前返回加载器 ✅ 始终依赖 Suspense 边界

用户反馈

• 仅使用 useMuiSnackbar
• 不使用第三方 Toast 库

---

10. 性能默认要求

• 对开销较大的派生计算使用 useMemo
• 对传递的处理函数使用 useCallback
• 对开销较大的纯组件使用 React.memo
• 对搜索进行防抖（300–500ms）
• 清理副作用，避免内存泄漏

性能回退就是 Bug。

---

11. TypeScript 规范

• 启用严格模式
• 不使用隐式 any
• 显式声明返回类型
• 为公共接口编写 JSDoc
• 将类型与功能代码放在一起

---

12. 标准文件结构

src/
  features/
    my-feature/
      api/
      components/
      hooks/
      helpers/
      types/
      index.ts

  components/
    SuspenseLoader/
    CustomAppBar/

  routes/
    my-route/
      index.tsx

---

13. 标准组件模板

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('');

  const { data } = useSuspenseQuery<FeatureData>({
    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;

---

14. 反模式（立即拒绝）

❌ 提前返回加载状态 ❌ 在 components/ 中编写功能逻辑 ❌ 使用属性逐层传递共享状态，而不是使用钩子 ❌ 内联调用 API ❌ 响应未指定类型 ❌ 在一个组件中承担多项职责

---

15. 与其他技能集成

• frontend-design → 视觉系统与美学
• page-cro → 布局层级与转化逻辑
• analytics-tracking → 事件埋点
• backend-dev-guidelines → API 契约对齐
• error-tracking → 运行时可观测性

---

16. 操作员验证清单

完成代码前：

• FFCI ≥ 6
• 正确使用 Suspense
• 遵守功能边界
• 没有提前返回
• 类型明确且正确
• 已应用延迟加载
• 性能安全

---

17. 技能状态

状态： 稳定、立场鲜明且可执行 适用范围： 需要长期维护的生产级 React 代码库

使用时机

当任务明确符合概述中描述的工作流或操作时，可使用此技能。

限制

• 仅当任务明确符合上述范围时才使用此技能。
• 不要将输出视为针对特定环境进行验证、测试或专家审查的替代方案。
• 如果缺少必要输入、权限、安全边界或成功标准，请停止并请求澄清。

应用前提与限制

SuspenseLoader、LoadingOverlay、useMuiSnackbar、useAuth 和 apiClient 是项目专用示例，不包含可直接使用的实现。使用前请提供或调整这些示例。FFCI 是参考性启发式指标，并非经过验证的可行性或性能门槛。Suspense 本身不能避免布局偏移；请预留与回退内容相匹配的空间。在钩子调用无条件执行，且已处理加载、错误和空状态时，使用常规 useQuery 和提前返回都是有效做法。应通过性能分析决定是否使用记忆化和延迟加载边界，而不是机械套用。仍需进行服务端授权和运行时响应验证；TypeScript 无法验证网络数据。