面向现代 React + TypeScript 应用的有主见的(opinionated)前端开发标准。涵盖 Suspense 优先的数据获取、懒加载、基于功能的
前端开发指南是一项面向实际任务的技能,主要用于(React · TypeScript · Suspense 优先 · 生产级);你是一位 高级前端工程师 ,在严格的架构与性能标准下工作;
严格的 TypeScript 纪律;性能安全的默认值;本技能定义的是 前端代码必须如何书写 ,而不仅仅是如何。它将相关步骤、工具调用和结果整理方式集中到统一流程中,帮助使用者更快完成目标并减少重复操作。
从功能定位来看,该技能强调把分散的操作要求整理成清晰、可复用的处理流程,使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数,再依据技能说明逐步执行;若输入条件不完整,应先补齐信息或采用保守配置,避免因错误假设导致结果偏离需求。执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期,并对异常提示、缺失字段和边界情况进行处理;涉及批量任务时,还应保存进度,避免中断后重复操作。
(React · TypeScript · Suspense 优先 · 生产级)
你是一位高级前端工程师,在严格的架构与性能标准下工作。
你的目标是使用以下方式构建可扩展、可预测、可维护的 React 应用:
本技能定义的是前端代码必须如何书写,而不仅仅是如何可以书写。
在实现组件、页面或功能之前,先评估可行性。
| 维度 | 问题 |
|---|---|
| 架构契合度 | 这是否与基于功能的架构和 Suspense 模型一致? |
| 复杂度负载 | 状态、数据与交互逻辑有多复杂? |
| 性能风险 | 是否会引入渲染、打包或 CLS 风险? |
| 可复用性 | 是否无需修改即可复用? |
| 维护成本 | 6 个月后要理解它会多难? |
FFCI = (架构契合度 + 可复用性 + 性能) − (复杂度 + 维护成本)
范围: -5 → +15
| FFCI | 含义 | 行动 |
|---|---|---|
| 10–15 | 优秀 | 继续 |
| 6–9 | 可接受 | 谨慎继续 |
| 3–5 | 有风险 | 简化或拆分 |
| ≤ 2 | 较差 | 重新设计 |
useSuspenseQuery 是首要的数据获取 hookisLoading 条件判断features/components/anyimport type*在以下情况使用 frontend-dev-guidelines:
React.FC 配合显式的 props 接口* 中*useSuspenseQuery 获取数据*useCallback 中*useMuiSnackbar 做反馈*features/{feature-name}/*api/、components/、hooks/、helpers/、types/*api/ 中*index.ts 公开导出*routes/ 下*| 别名 | 路径 |
|---|---|
@/ |
src/ |
~types |
src/types |
~components |
src/components |
~features |
src/features |
必须一致使用别名。不鼓励超过一级的相对导入。
useMemo)useCallback)const HeavyComponent = React.lazy(() => import('./HeavyComponent'));
始终包裹在 中。
useSuspenseQuery❌ isLoading
❌ 手动 spinner
❌ 组件内的 fetch 逻辑*
❌ 没有功能 API 层的 API 调用*
/api/ 前缀*export const Route = createFileRoute('/my-route/')({
component: MyPage,
loader: () => ({ crumb: 'My Route' }),
});
<100 行:内联 sx>100 行:{Component}.styles.ts// ✅ // ❌
对主题的访问必须始终类型安全。
❌ 绝不提前返回 loader ✅ 始终依赖 Suspense 边界*
useMuiSnackbar*useMemo*useCallback*React.memo*性能回退就是 bug。
any*src/
features/
my-feature/
api/
components/
hooks/
helpers/
types/
index.ts
components/
SuspenseLoader/
CustomAppBar/
routes/
my-route/
index.tsx
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 = ({ id, onAction }) => {
const [state, setState] = useState('');
const { data } = useSuspenseQuery({
queryKey: ['feature', id],
queryFn: () => featureApi.getFeature(id),
});
const handleAction = useCallback(() => {
setState('updated');
onAction?.();
}, [onAction]);
return (
{/* Content */}
);
};
export default MyComponent;
❌ 提前返回 loader
❌ 功能逻辑放在 components/ 中*
❌ 用 prop 透传而非 hooks 来共享状态*
❌ 内联 API 调用*
❌ 未类型化的响应*
❌ 一个组件承担多重职责*
在收尾代码之前:
状态: 稳定、有主见、可强制* 预期用途: 具有长期维护周期的生产级 React 代码库*
相关专题
热门下载
相关下载
精品课程
共6课时 | 54.7万人学习
共89课时 | 134.3万人学习
共49课时 | 82.7万人学习
最新文章