React 项目规范

适用于使用 React + TypeScript 的仓库。

项目结构

以下为中大型 React 项目的业界最佳实践结构，按项目实际情况裁剪：

src/
├── app/ # 应用入口与全局配置
│ ├── App.tsx # 根组件（Provider 组合）
│ ├── routes.tsx # 路由配置
│ └── providers.tsx # 全局 Provider 组装
│
├── pages/ # 页面组件（与路由一一对应）
│ ├── Dashboard/
│ │ ├── DashboardPage.tsx
│ │ ├── components/ # 页面私有组件
│ │ └── hooks/ # 页面私有 hooks
│ ├── UserList/
│ └── Settings/
│
├── layouts/ # 布局组件
│ ├── MainLayout.tsx # 主布局（侧边栏 + 顶栏 + 内容区）
│ ├── AuthLayout.tsx # 登录/注册页布局
│ └── BlankLayout.tsx # 空白布局（错误页等）
│
├── features/ # 功能模块（按业务领域划分）
│ ├── auth/
│ │ ├── components/ # 模块组件
│ │ ├── hooks/ # 模块 hooks
│ │ ├── api.ts # 模块 API 调用
│ │ ├── types.ts # 模块类型定义
│ │ ├── constants.ts # 模块常量
│ │ └── index.ts # 模块公开导出
│ └── order/
│
├── components/ # 全局共享 UI 组件
│ ├── Button/
│ │ ├── Button.tsx
│ │ ├── Button.module.css
│ │ └── tests/
│ ├── Modal/
│ ├── Form/
│ └── ErrorBoundary/
│
├── hooks/ # 全局共享 hooks
│ ├── useAuth.ts
│ ├── useDebounce.ts
│ └── useMediaQuery.ts
│
├── services/ # API 基础层
│ ├── request.ts # Axios/fetch 实例与拦截器
│ └── endpoints/ # API 端点定义（如按领域拆分）
│
├── stores/ # 全局状态管理
│ ├── authStore.ts
│ └── uiStore.ts
│
├── locales/ # 国际化语言包
│ ├── zh-CN.json # 中文
│ ├── en-US.json # 英文
│ └── index.ts # i18n 实例初始化（i18next / react-intl）
│
├── assets/ # 静态资源
│ ├── images/ # 图片（PNG、JPG、WebP）
│ ├── icons/ # SVG 图标
│ └── fonts/ # 自定义字体
│
├── config/ # 应用配置
│ ├── env.ts # 环境变量类型化封装
│ └── features.ts # Feature Flags 管理
│
├── types/ # 全局共享类型
│ ├── api.ts # API 响应/请求通用类型
│ ├── models.ts # 业务实体类型
│ └── global.d.ts # 全局类型扩展（图片模块声明等）
│
├── utils/ # 纯工具函数
│ ├── format.ts # 日期、数字、货币格式化
│ ├── validators.ts # 表单校验规则
│ └── storage.ts # LocalStorage / SessionStorage 封装
│
├── styles/ # 全局样式与主题
│ ├── global.css # 全局基础样式（reset / normalize）
│ ├── variables.css # CSS 变量（颜色、间距、字号）
│ ├── breakpoints.ts # 响应式断点常量
│ └── themes/ # 主题定义
│ ├── light.css # 亮色主题变量
│ ├── dark.css # 暗色主题变量
│ └── index.ts # 主题切换逻辑
│
└── constants/ # 全局常量
├── routes.ts # 路由路径常量
└── config.ts # 业务常量（分页大小、超时时间等）

关键原则

• - pages/ 做路由映射和布局组合，不放业务逻辑
• layouts/ 定义页面骨架（侧边栏、顶栏、面包屑），由路由配置引用
• features/ 按业务领域划分，模块内自包含（components + hooks + api + types）
• components/ 仅放无业务耦合的通用组件，可跨项目复用
• hooks/ 仅放通用逻辑（防抖、媒体查询等），业务 hooks 放到对应 feature 中
• locales/ 存放语言包 JSON 文件，组件中使用 t(key) 而非硬编码文案
• assets/ 存放静态资源，图标优先使用 SVG，图片优先使用 WebP/AVIF
• config/ 封装环境变量和 Feature Flags，禁止组件中直接读取 import.meta.env
• styles/themes/ 通过 CSS 变量实现主题切换，组件中引用变量而非硬编码颜色
• 每个模块通过 index.ts 管控公开 API，避免深层路径导入

组件设计规范

• - 使用函数组件和 TypeScript
• 保持组件职责单一、可组合
• 将可复用逻辑提取到 hooks
• 在合适场景优先使用受控组件 API
• props 定义清晰且类型明确
• 优先复用现有设计系统组件
• 保持可访问性与键盘交互
• 避免过深的 JSX 嵌套和重复分支
• 对可推导的值不要额外存 state

组件文件结构

ComponentName/
├── ComponentName.tsx
├── ComponentName.types.ts # 类型定义（如需独立）
├── ComponentName.module.css # 样式（如需）
├── hooks/
│ └── useComponentLogic.ts
├── components/
│ └── SubComponent.tsx
└── tests/
└── ComponentName.spec.tsx

组件分层

页面组件 (Pages) → 路由映射、布局组合
└── 容器组件 (Containers) → 数据获取、状态编排
└── 业务组件 (Features) → 领域逻辑展示
└── 通用组件 (UI) → 纯展示，无业务耦合

TypeScript 规范

• - Props interface 命名: ComponentNameProps
• 事件处理函数: handle 前缀（如 handleClick）
• 回调 Props: on 前缀（如 onChange、onSubmit）
• 禁止使用 any，优先使用 unknown 或精确类型
• 泛型组件使用 约束，保持类型推导

tsx
interface TableProps> {
data: T[];
columns: ColumnDef[];
onRowClick?: (row: T) => void;
}

Hooks 规范

自定义 Hook 设计

• - 以 use 前缀命名
• 返回值使用对象（而非数组），方便按需解构
• 状态和行为封装在一起，组件只消费结果
• Hook 内部处理 loading / error / data 三态

tsx
function useUserList(params: QueryParams) {
const [data, setData] = useState([]);
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);

const fetch = useCallback(async () => {
setLoading(true);
setError(null);
try {
const res = await getUserList(params);
setData(res.list);
} catch (e) {
setError(e as Error);
} finally {
setLoading(false);
}
}, [params]);

useEffect(() => { fetch(); }, [fetch]);

return { data, loading, error, refetch: fetch };
}

Hook 使用原则

• - useEffect 必须有正确的依赖数组和清理函数
• useMemo / useCallback 仅在子组件使用 memo 或依赖稳定性重要时使用
• 不要在条件分支或循环中调用 hooks
• 数据请求场景优先使用 React Query / SWR 等库（如项目已引入）

路由规范

路由组织

tsx
// app/routes.tsx
const routes: RouteObject[] = [
{
path: /,
element: ,
children: [
{ index: true, element