frontend-dev-guidelines

Polar Sponsor
爱发电 赞助
.NET 9.0

面向现代 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. 组件标准

必需的结构顺序

  1. 类型 / Props
  2. Hooks
  3. 派生值(useMemo)
  4. 处理函数(useCallback)
  5. 渲染
  6. 默认导出

懒加载模式

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 代码库*

相关专题

更多
GoFrame框架Web开发与路由中间件
GoFrame框架Web开发与路由中间件

本专题聚焦GoFrame框架的Web开发,拆解路由注册与匹配规则、请求参数获取、参数校验与中间件执行顺序,说明统一响应、JWT鉴权、文件上传与接口文档生成的落地方式,并补充优雅重启与测试实践。

2026.11.17

0

15

GoFrame框架安装与gf命令行工具
GoFrame框架安装与gf命令行工具

本专题围绕GoFrame框架的安装与工具链配置展开,讲清Go版本要求、gf命令行的安装方式、代理镜像与依赖准备,说明项目初始化、热编译、交叉编译打包的做法,并整理安装阶段的常见报错与验证步骤。

2026.11.17

0

15

GoFrame框架零基础入门
GoFrame框架零基础入门

本专题整理GoFrame框架的入门知识,从模块化设计理念、环境准备到跑通第一个Web服务,讲清目录分层、配置加载、日志与中间件的用法,并对比Gin、Go-Zero的差异,帮助Go开发者建立整体认知。

2026.11.17

0

15

SQLAlchemy 一对多关系怎么建立
SQLAlchemy 一对多关系怎么建立

SQLAlchemy 一对多关系怎么建立?本专题整理父子表外键、relationship 双向映射、关联查询、级联删除和加载优化等相关文章,帮助你理解并实现常见的 ORM 关系建模。

2026.11.17

0

10

SQLAlchemy 如何增删改查
SQLAlchemy 如何增删改查

SQLAlchemy 如何增删改查?本专题整理 ORM 新增记录、条件查询、更新和删除、Session 事务提交与批量处理等实用文章,帮助你掌握 Python 数据库操作流程。

2026.11.17

0

11

SQLAlchemy ORM 模型怎么写
SQLAlchemy ORM 模型怎么写

SQLAlchemy ORM 模型怎么写?本专题整理模型类定义、Mapped 字段映射、主键与约束、表结构创建和常见报错的相关文章,帮助你从基础配置到实际建模逐步掌握 SQLAlchemy。

2026.11.17

0

16

Go-Zero API开发使用教程
Go-Zero API开发使用教程

本专题聚焦Go-Zero的API开发,拆解.api描述文件的语法结构、路由与分组定义、参数绑定与校验规则,说明统一响应体、JWT鉴权、跨域与接口文档生成的落地方式,并给出网关聚合与接口测试的实践建议。

2026.11.12

0

15

Go-Zero安装与goctl环境配置教程
Go-Zero安装与goctl环境配置教程

本专题围绕Go-Zero的安装与工具链配置展开,讲清Go版本要求、goctl安装方式、代理镜像、protoc依赖与环境变量设置,说明多版本共存、升级回退与CI流水线安装的做法,并整理安装阶段的常见报错与验证步骤。

2026.11.12

0

15

Go-Zero零基础入门教程
Go-Zero零基础入门教程

本专题整理Go-Zero的入门知识,从框架定位、环境准备到跑通第一个API服务,讲清目录分层、配置加载、日志与中间件的基本用法,并对比Gin、Kratos的差异,帮助Go开发者建立整体认知,判断它是否适合当前项目。

2026.11.12

0

15

热门下载

更多
网站特效
/
网站源码
/
网站素材
/
前端模板

精品课程

更多
热门推荐
/
最新课程
phpStudy极速入门视频教程
phpStudy极速入门视频教程

共6课时 | 54.7万人学习

独孤九贱(4)_PHP视频教程
独孤九贱(4)_PHP视频教程

共89课时 | 134.3万人学习