面向现代 React + TypeScript 应用的有主见的(opinionated)前端开发标准。涵盖 Suspense 优先的数据获取、懒加载、基于功能的
前端开发指南
功能概述
前端开发指南是一项面向实际任务的技能,主要用于(React · TypeScript · Suspense 优先 · 生产级);你是一位 高级前端工程师 ,在严格的架构与性能标准下工作;
核心要点
- 你的目标是使用以下方式构建 可扩展、可预测、可维护的 React 应用 :;
- Suspense 优先的数据获取;
- 基于功能的代码组织;
使用与执行
严格的 TypeScript 纪律;性能安全的默认值;本技能定义的是 前端代码必须如何书写 ,而不仅仅是如何。它将相关步骤、工具调用和结果整理方式集中到统一流程中,帮助使用者更快完成目标并减少重复操作。
结果检查与注意事项
从功能定位来看,该技能强调把分散的操作要求整理成清晰、可复用的处理流程,使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数,再依据技能说明逐步执行;若输入条件不完整,应先补齐信息或采用保守配置,避免因错误假设导致结果偏离需求。执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期,并对异常提示、缺失字段和边界情况进行处理;涉及批量任务时,还应保存进度,避免中断后重复操作。
前端开发指南
(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* - 类型是一等公民的设计产物*
3. 何时使用本技能
在以下情况使用 frontend-dev-guidelines:
- 创建组件或页面*
- 添加新功能*
- 获取或变更数据*
- 配置路由*
- 使用 MUI 样式*
- 处理性能问题*
- 审查或重构前端代码*
4. 快速开始检查清单
新组件检查清单
-
React.FC配合显式的 props 接口* - 若非平凡则懒加载*
- 包裹在
中* - 使用
useSuspenseQuery获取数据* - 无提前返回*
- 处理函数包裹在
useCallback中* - 若 <100 行则内联样式*
- 底部默认导出*
- 使用
useMuiSnackbar做反馈*
新功能检查清单
- 创建
features/{feature-name}/* - 子目录:
api/、components/、hooks/、helpers/、types/* - API 层隔离在
api/中* - 通过
index.ts公开导出* - 功能入口懒加载*
- 功能级 Suspense 边界*
- 路由定义在
routes/下*
5. 导入别名(必需)
| 别名 | 路径 |
|---|---|
@/ |
src/ |
~types |
src/types |
~components |
src/components |
~features |
src/features |
必须一致使用别名。不鼓励超过一级的相对导入。
6. 组件标准
必需的结构顺序
- 类型 / Props
- Hooks
- 派生值(
useMemo) - 处理函数(
useCallback) - 渲染
- 默认导出
懒加载模式
const HeavyComponent = React.lazy(() => import('./HeavyComponent'));
始终包裹在 中。
7. 数据获取准则
首要模式
useSuspenseQuery- 缓存优先*
- 类型化响应*
禁止模式
❌ isLoading
❌ 手动 spinner
❌ 组件内的 fetch 逻辑*
❌ 没有功能 API 层的 API 调用*
API 层规则
- 每个功能一个 API 文件*
- 不要内联 axios 调用*
- 路由中不要
/api/前缀*
8. 路由标准(TanStack Router)
- 仅基于文件夹的路由*
- 懒加载路由组件*
- 通过 loader 提供面包屑元数据*
export const Route = createFileRoute('/my-route/')({
component: MyPage,
loader: () => ({ crumb: 'My Route' }),
});
9. 样式标准(MUI v7)
内联 vs 分离
<100 行:内联sx>100 行:{Component}.styles.ts
网格语法(仅 v7)
// ✅ // ❌
对主题的访问必须始终类型安全。
10. 加载与错误处理
绝对规则
❌ 绝不提前返回 loader ✅ 始终依赖 Suspense 边界*
用户反馈
- 仅
useMuiSnackbar* - 不要第三方 toast 库*
11. 性能默认值
- 对昂贵的派生使用
useMemo* - 对传入的处理函数使用
useCallback* - 对重型纯组件使用
React.memo* - 防抖搜索(300–500ms)*
- 清理 effect 以避免泄漏*
性能回退就是 bug。
12. TypeScript 标准
- 启用严格模式*
- 不要隐式
any* - 显式返回类型*
- 对公开接口加 JSDoc*
- 类型与功能就近放置*
13. 规范文件结构
src/
features/
my-feature/
api/
components/
hooks/
helpers/
types/
index.ts
components/
SuspenseLoader/
CustomAppBar/
routes/
my-route/
index.tsx
14. 规范组件模板
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;
15. 反模式(立即驳回)
❌ 提前返回 loader
❌ 功能逻辑放在 components/ 中*
❌ 用 prop 透传而非 hooks 来共享状态*
❌ 内联 API 调用*
❌ 未类型化的响应*
❌ 一个组件承担多重职责*
16. 与其他技能的集成
- frontend-design → 视觉系统与美学*
- page-cro → 布局层级与转化逻辑*
- analytics-tracking → 事件埋点*
- backend-dev-guidelines → API 契约对齐*
- error-tracking → 运行时可观测性*
17. 操作者验证清单
在收尾代码之前:
- FFCI ≥ 6
- Suspense 使用正确*
- 功能边界被遵守*
- 无提前返回*
- 类型显式且正确*
- 已应用懒加载*
- 性能安全*
18. 技能状态
状态: 稳定、有主见、可强制* 预期用途: 具有长期维护周期的生产级 React 代码库*
热门AI工具
相关专题
本专题聚焦GoFrame框架的Web开发,拆解路由注册与匹配规则、请求参数获取、参数校验与中间件执行顺序,说明统一响应、JWT鉴权、文件上传与接口文档生成的落地方式,并补充优雅重启与测试实践。
0
2026.11.17
本专题围绕GoFrame框架的安装与工具链配置展开,讲清Go版本要求、gf命令行的安装方式、代理镜像与依赖准备,说明项目初始化、热编译、交叉编译打包的做法,并整理安装阶段的常见报错与验证步骤。
0
2026.11.17
本专题整理GoFrame框架的入门知识,从模块化设计理念、环境准备到跑通第一个Web服务,讲清目录分层、配置加载、日志与中间件的用法,并对比Gin、Go-Zero的差异,帮助Go开发者建立整体认知。
0
2026.11.17
SQLAlchemy 一对多关系怎么建立?本专题整理父子表外键、relationship 双向映射、关联查询、级联删除和加载优化等相关文章,帮助你理解并实现常见的 ORM 关系建模。
0
2026.11.17
SQLAlchemy 如何增删改查?本专题整理 ORM 新增记录、条件查询、更新和删除、Session 事务提交与批量处理等实用文章,帮助你掌握 Python 数据库操作流程。
0
2026.11.17
SQLAlchemy ORM 模型怎么写?本专题整理模型类定义、Mapped 字段映射、主键与约束、表结构创建和常见报错的相关文章,帮助你从基础配置到实际建模逐步掌握 SQLAlchemy。
0
2026.11.17
本专题聚焦Go-Zero的API开发,拆解.api描述文件的语法结构、路由与分组定义、参数绑定与校验规则,说明统一响应体、JWT鉴权、跨域与接口文档生成的落地方式,并给出网关聚合与接口测试的实践建议。
0
2026.11.12
本专题围绕Go-Zero的安装与工具链配置展开,讲清Go版本要求、goctl安装方式、代理镜像、protoc依赖与环境变量设置,说明多版本共存、升级回退与CI流水线安装的做法,并整理安装阶段的常见报错与验证步骤。
0
2026.11.12
本专题整理Go-Zero的入门知识,从框架定位、环境准备到跑通第一个API服务,讲清目录分层、配置加载、日志与中间件的基本用法,并对比Gin、Kratos的差异,帮助Go开发者建立整体认知,判断它是否适合当前项目。
0
2026.11.12
热门下载
相关下载
精品课程
共6课时 | 12.1万人学习
共79课时 | 161.9万人学习
共6课时 | 54.8万人学习
最新文章