用途:为 React 应用提供企业级架构规范,核心思想是“按领域思考而非按页面思考”,把 DDD 与 FSD 融合成具有单向依赖的分层结构。
主要能力:
- FSD 分层:App → Pages → Widgets → Features → Entities → Shared,各层只依赖下层,不出现向上依赖;按领域划分 slices(如 features/cart、features/auth),内部使用 ui/、model/、api/、lib/、config/、index.ts 等 segments。
- 组件结构采用 Index/Types/Styles 模式:index.tsx 放 React 逻辑与 JSX,types.ts 放 TypeScript 接口,styles.ts 放 CSS-in-JS(Emotion/styled-components),在文件系统层面分离关注点。
- 数据层 Service/Hook 一对一映射:Service 层为纯 TypeScript、与 React 无关,负责 API 调用与 DTO;Hook 层用 React Query 处理缓存与 loading/error 状态;一个 service 函数对应一个自定义 hook,query key 使用工厂模式。
- 状态管理:React Query 管理服务端状态,Zustand 管理客户端状态(主题、弹窗、复杂表单),store 放在领域对应的 model/ 片段中,使用 slice 模式并优化 selector。
- TypeScript 约定:组件与接口用 PascalCase,变量与布尔值用 camelCase(is/has/should/can 前缀),常量用 UPPER_SNAKE,hook 用 camelCase 且以 use 开头;要求严格类型、不用 any。
使用方式:按任务加载对应参考文档,如架构设计读 references/ddd-fsd-fundamentals.md,目录结构读 references/fsd-layers-guide.md,组件创建读 references/component-structure.md,数据层读 references/data-layer-architecture.md,状态管理读 references/state-management.md,代码规范读 references/typescript-conventions.md。技能提供脚本:python scripts/create_fsd_structure.py <project-root> [--slices cart auth user] 创建目录结构;python scripts/create_component.py <path> <ComponentName> 生成组件;python scripts/create_service_hook.py <feature-path> <service-name> 生成 Service/Hook 对及 Query Key 工厂;python scripts/create_zustand_store.py <feature-path> <store-name> 生成带 selector 与 action 的 store。
适用场景:需要统一 React 项目架构与目录规范、控制模块依赖方向、规范类型命名与数据获取模式的团队。
限制:资料未说明安装与运行环境要求、支持的 React 或 TypeScript 版本、具体依赖包配置、脚本是否需要额外参数或前置条件、收费方式,以及实际项目验证效果,这些暂未提供;采用前需自行确认脚本运行环境。