frontend-dev-guidelines

Frontend Dev Guidelines - React TypeScript 开发规范

技能概述

Frontend Dev Guidelines 是一套面向现代 React + TypeScript 应用的前端开发规范，帮助团队构建可扩展、可预测、易维护的生产级代码。

适用场景

新建 React 组件或页面

提供标准化的组件模板和代码结构顺序，确保新代码从开始就符合团队规范。

重构或审查现有代码

通过 FFCI（前端可行性复杂度指数）评估代码质量，识别需要简化的复杂组件。

团队协作和代码一致性

统一数据获取、路由配置、样式编写等核心实践，减少团队内的代码风格差异。

核心功能

Suspense 优先数据获取

使用 useSuspenseQuery 作为主要数据获取方式，禁用手动的 isLoading 判断和提前返回的加载状态，让 Suspense 边界统一处理加载状态。

特性驱动代码组织

要求领域逻辑放在 features/ 目录，可复用组件放在 components/ 目录，禁止跨功能耦合，保持代码边界清晰。

严格的 TypeScript 纪律

禁用 any 类型，要求显式返回类型，使用 import type 导入类型，将类型作为一等设计工件来对待。

常见问题

什么是 FFCI，如何使用？

FFCI（Frontend Feasibility & Complexity Index）是前端可行性复杂度指数，用于评估组件或功能实现的价值。计算公式为：(架构适配性 + 可复用性 + 性能) − (复杂度 + 维护成本)，得分范围 -5 到 +15。得分 10–15 可以直接实施，6–9 需谨慎处理，≤2 需要重新设计。

为什么禁止使用 isLoading？

传统的 isLoading 模式会导致组件内部出现大量条件判断和提前返回，增加代码复杂度。使用 Suspense 可以将加载状态处理从组件逻辑中剥离，由 Suspense 边界统一管理，让组件专注于渲染逻辑，提高代码可读性和可维护性。

组件代码应该按什么顺序组织？

推荐顺序为：1) Types/Props 定义 → 2) Hooks → 3) 派生值（useMemo）→ 4) 事件处理函数（useCallback）→ 5) 渲染逻辑 → 6) 默认导出。这种顺序符合数据流动方向，便于阅读和理解组件。