frontend-dev-guidelines
下载地址
https://www.zhengdianxue.com/wp-content/uploads/skills/org-02qudk26--frontend-dev-guidelines.zip将提示词发送给你的 AI 安装该 skills
请根据 https://skillhub.cn/install/skillhub.md,安装 @org-02qudk26/frontend-dev-guidelines。面向现代 React + TypeScript 应用的有主见的(opinionated)前端开发标准。涵盖 Suspense 优先的数据获取、懒加载、基于功能的
阅读全文 (展开查看完整说明)
概述
前端开发指南
(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>配合显式的 props 接口* - [ ] 若非平凡则懒加载*
- [ ] 包裹在
<SuspenseLoader>中* - [ ] 使用
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'));始终包裹在 <SuspenseLoader> 中。
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)
<Grid size={{ xs: 12, md: 6 }} /> // ✅
<Grid xs={12} md={6} /> // ❌对主题的访问必须始终类型安全。
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.tsx14. 规范组件模板
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;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 代码库*