frontend-design-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Frontend Design Patterns

前端设计模式

Enterprise-grade React architecture combining Domain-Driven Design (DDD) and Feature-Sliced Design (FSD) with strict TypeScript conventions.

结合**领域驱动设计(DDD)与功能切片设计(FSD)**模式的企业级React架构，搭配严格的TypeScript规范。

Core Patterns

核心模式

1. DDD + FSD Hybrid Architecture

1. DDD + FSD混合架构

Philosophy: Think in domains, not pages
Structure: Layered architecture with unidirectional dependencies
Key Concept: Features (user actions) vs Entities (data representation)

Reference: See

references/ddd-fsd-fundamentals.md

for detailed DDD/FSD fusion strategy.

设计理念: 以领域为核心思考，而非页面
架构结构: 单向依赖的分层架构
核心概念: 功能（用户操作）与实体（数据表示）的区分

参考文档: 详见

references/ddd-fsd-fundamentals.md

获取DDD/FSD融合策略的详细内容。

2. FSD Layer Hierarchy

2. FSD分层体系

App -> Pages -> Widgets -> Features -> Entities -> Shared

Each layer only depends on layers below it. No upward dependencies.

Slices: Domain-based directories (e.g.,
```
features/cart
```
,
```
features/auth
```
)
Segments:
```
ui/
```
,
```
model/
```
,
```
api/
```
,
```
lib/
```
,
```
config/
```
,
```
index.ts
```

Reference: See

references/fsd-layers-guide.md

for complete layer definitions.

App -> Pages -> Widgets -> Features -> Entities -> Shared

每个层仅依赖其下方的层，禁止向上依赖。

切片: 基于领域的目录（例如
```
features/cart
```
、
```
features/auth
```
）
模块:
```
ui/
```
、
```
model/
```
、
```
api/
```
、
```
lib/
```
、
```
config/
```
、
```
index.ts
```

参考文档: 详见

references/fsd-layers-guide.md

获取完整的层定义说明。

3. Component Structure: Index/Types/Styles

3. 组件结构：Index/Types/Styles

ComponentName/
├── index.tsx    # React logic & JSX
├── types.ts     # TypeScript interfaces
└── styles.ts    # CSS-in-JS (Emotion/styled-components)

Separates concerns at filesystem level. Improves collaboration and reduces merge conflicts.

Reference: See

references/component-structure.md

for implementation details.

ComponentName/
├── index.tsx    # React逻辑与JSX代码
├── types.ts     # TypeScript接口定义
└── styles.ts    # CSS-in-JS（Emotion/styled-components）

在文件系统层面实现关注点分离，提升协作效率并减少代码合并冲突。

参考文档: 详见

references/component-structure.md

获取实现细节。

4. Data Layer: Service/Hook 1:1 Mapping

4. 数据层：Service/Hook 1:1映射

Service Layer (Pure TS) -> Hook Layer (React Query) -> Components

Service: API calls, DTOs (React-agnostic)
Hook: React Query integration, caching, loading/error states
Rule: One service function = one custom hook
Query Keys: Use factory pattern

Reference: See

references/data-layer-architecture.md

for Axios/React Query setup.

服务层（纯TS代码） -> Hook层（React Query） -> 组件

Service: API调用、DTO（与React无关）
Hook: React Query集成、缓存处理、加载/错误状态管理
规则: 一个服务函数对应一个自定义Hook
查询键: 使用工厂模式

参考文档: 详见

references/data-layer-architecture.md

获取Axios/React Query的配置方法。

5. State Management: Zustand + React Query

5. 状态管理：Zustand + React Query

React Query: Server state (API data, caching)
Zustand: Client state (theme, modals, complex forms)
Store Location: Domain-specific in
```
model/
```
segment
Pattern: Slice pattern with selector optimization

Reference: See

references/state-management.md

for Zustand patterns.

React Query: 服务端状态（API数据、缓存）
Zustand: 客户端状态（主题、弹窗、复杂表单）
存储位置: 领域专属的
```
model/
```
模块中
模式: 带选择器优化的切片模式

参考文档: 详见

references/state-management.md

获取Zustand使用模式。

6. TypeScript Conventions

6. TypeScript规范

Target	Case	Example
Component	PascalCase	`UserProfile`
Interface	PascalCase	`UserProfileProps`
Variable	camelCase	`userList` , `isLoading`
Boolean	camelCase	`is` , `has` , `should` , `can` prefix
Constant	UPPER_SNAKE	`MAX_COUNT`
Hook	camelCase	`useAuth` , `useWindowSize`

Reference: See

references/typescript-conventions.md

for complete rules.

目标对象	命名格式	示例
组件	PascalCase	`UserProfile`
接口	PascalCase	`UserProfileProps`
变量	camelCase	`userList` , `isLoading`
布尔值	camelCase	前缀为 `is` 、 `has` 、 `should` 、 `can`
常量	UPPER_SNAKE	`MAX_COUNT`
Hook	camelCase	`useAuth` , `useWindowSize`

参考文档: 详见

references/typescript-conventions.md

获取完整规则。

Workflow

工作流程

Load references based on current task:

Task	Reference
Architecture design	`references/ddd-fsd-fundamentals.md`
Folder structure	`references/fsd-layers-guide.md`
Component creation	`references/component-structure.md`
API/Data layer	`references/data-layer-architecture.md`
State management	`references/state-management.md`
Code conventions	`references/typescript-conventions.md`

根据当前任务加载对应参考文档：

任务	参考文档
架构设计	`references/ddd-fsd-fundamentals.md`
文件夹结构规划	`references/fsd-layers-guide.md`
组件创建	`references/component-structure.md`
API/数据层搭建	`references/data-layer-architecture.md`
状态管理配置	`references/state-management.md`
代码规范落地	`references/typescript-conventions.md`

Scripts

脚本工具

Create FSD Structure

创建FSD结构

bash

python scripts/create_fsd_structure.py <project-root> [--slices cart auth user]

Creates complete FSD folder structure with standard segments.

bash

python scripts/create_fsd_structure.py <project-root> [--slices cart auth user]

创建包含标准模块的完整FSD文件夹结构。

Create Component

创建组件

bash

python scripts/create_component.py <path> <ComponentName>

Generates Index/Types/Styles pattern component.

bash

python scripts/create_component.py <path> <ComponentName>

生成符合Index/Types/Styles模式的组件。

Create Service/Hook Pair

创建Service/Hook配对

bash

python scripts/create_service_hook.py <feature-path> <service-name>

Generates Service Layer + Hook Layer with Query Key factory.

bash

python scripts/create_service_hook.py <feature-path> <service-name>

生成服务层+Hook层代码，包含查询键工厂。

Create Zustand Store

创建Zustand存储

bash

python scripts/create_zustand_store.py <feature-path> <store-name>

Generates Zustand store with selectors and actions.

bash

python scripts/create_zustand_store.py <feature-path> <store-name>

生成带选择器与操作方法的Zustand存储。

Key Principles

核心原则

Separation of Concerns: UI, logic, styles separated at filesystem level
Unidirectional Dependencies: Layers only depend on lower layers
Explicit Dependencies: No circular references
Type Safety: Strict TypeScript, no
```
any
```
Single Responsibility: Each file/module has one clear purpose

关注点分离: UI、逻辑、样式在文件系统层面分离
单向依赖: 层仅依赖下层
显式依赖: 禁止循环引用
类型安全: 严格的TypeScript规范，禁止使用
```
any
```
单一职责: 每个文件/模块仅承担一个明确职责