前端技术设计方法论 (The Frontend Design Methodology)
遵循 “从业务到架构，从抽象到具体，从决策到验证” 的逻辑闭环，分为五个核心阶段：
需求分析与边界界定 (Context & Constraints)
核心目标：明确“做什么”以及“不做什么”，识别非功能性需求。
- 业务映射：将产品需求转化为技术功能点（User Stories -> Technical Features）。
- 约束识别：
- 时间/资源：上线截止日期、人力配置。
- 技术债：现有系统的兼容性要求、遗留代码限制。
- 性能指标：首屏加载时间 (FCP/LCP)、交互延迟 (INP)、SEO 要求。
- 安全合规：数据隐私 (GDPR)、权限控制粒度。
- 产出物：需求技术映射表、非功能性需求清单 (NFR List)。
架构选型与决策 (Architecture & Decision Making)
核心目标：确定系统的骨架，通过 ADR (Architecture Decision Records) 记录关键决策。
- 渲染策略选择：根据内容类型决定 CSR (客户端渲染), SSR (服务端渲染), SSG (静态生成), 还是 ISR (增量静态再生)。2026 趋势：RSC (React Server Components) 或 Islands Architecture 的考量。
- 状态管理策略：区分服务器状态 (Server State, 如 TanStack Query) 和客户端状态 (Client State, 如 Zustand/Jotai)，避免过度封装。
- 模块化/微前端：评估是否需要微前端 (Module Federation, qiankun) 还是单体仓库 (Monorepo, Turborepo/Nx)。
- 技术栈锁定：框架版本、构建工具 (Vite/Rspack)、语言特性 (TypeScript strict mode)。
- 产出物：架构拓扑图、关键技术决策记录 (ADR)。
详细设计与规范制定 (Detailed Design & Standards)
核心目标：定义“怎么做”，确保代码一致性和可维护性。
- 目录结构规范：按功能 (Feature-based) 还是按类型 (Type-based) 组织文件。
- 组件设计原则：
- 原子设计理论 (Atomic Design) 的应用。
- Props 接口定义：使用 TypeScript Interface 严格定义。
- 受控/非受控策略。
- 数据流设计：API 接口定义 (OpenAPI/Swagger)、Mock 方案、错误处理机制、Loading 状态管理。
- 工程化配置：Lint 规则、Commit 规范、CI/CD 流水线设计、自动化测试策略 (Unit/E2E)。
- 产出物：组件层级图、数据流向图、API 契约、工程配置草案。
风险预估与预案 (Risk Assessment)
核心目标：提前识别潜在坑点。
- 兼容性风险：老旧浏览器支持方案 (Polyfill 策略)。
- 性能瓶颈：大包体积、长列表渲染、复杂计算场景。
- 第三方依赖：库的活跃度、License 风险、升级路径。
- 产出物：风险登记册 (Risk Register) 及应对方案。
评审与迭代 (Review & Iteration)
核心目标：集思广益，达成共识。
- 设计评审会：邀请后端、QA、产品参与，重点审查接口契约和边界情况。
- 原型验证：针对高风险模块进行快速代码验证。
前端技术设计文档模板 (Frontend Technical Design Template)
你可以直接复制以下 Markdown 内容作为项目的 DESIGN.md。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
| # [项目名称] 前端技术设计文档
| 属性 | 内容 |
| :----------- | :---------------------------- |
| **文档版本** | v1.0.0 |
| **撰写人** | [你的名字] |
| **最后更新** | 2026-03-05 |
| **状态** | 🟡 草稿 / 🟢 已评审 / 🔴 废弃 |
| **关联需求** | [PRD 链接/Jira Epic 链接] |
## 1. 概述 (Overview)
### 1.1 背景与目标
> 简述项目背景，为什么要做这个系统/功能？主要解决什么用户痛点？
> _示例：为了提升后台管理系统的加载速度，需将原有的 Webpack + CSR 架构迁移至 Vite + SSR 架构。_
### 1.2 适用范围
> 本文档涵盖的模块范围，以及明确**不包含**的内容。
### 1.3 术语表
| 术语 | 解释 |
| :--- | :---------------------- |
| RSC | React Server Components |
| BFF | Backend for Frontend |
## 2. 总体架构设计 (Architecture Design)
### 2.1 技术栈选型
| 领域 | 技术/工具 | 版本 | 选型理由 |
| :----------- | :---------------------- | :--------- | :----------------------------- |
| **核心框架** | React / Vue / Next.js | 19.x / 4.x | 社区生态、团队熟悉度、RSC 支持 |
| **构建工具** | Vite / Rspack | 6.x | 构建速度、HMR 体验 |
| **语言** | TypeScript | 5.7+ | 类型安全、智能提示 |
| **状态管理** | Zustand / Pinia | - | 轻量级、无样板代码 |
| **样式方案** | TailwindCSS / CSS-in-JS | - | 开发效率、按需打包 |
### 2.2 系统架构图
> [在此处插入架构图，推荐使用 Mermaid 或 Excalidraw 链接] > _展示：客户端、BFF 层、网关、后端服务、CDN、监控系统的交互关系。_
### 2.3 核心架构决策 (ADR)
> 记录关键的 Trade-off 分析。
- **决策 1**: 采用 SSR 而非 CSR。
- **原因**: SEO 需求及首屏性能要求 (LCP < 1.2s)。
- **代价**: 服务器成本增加，开发复杂度提升。
- **决策 2**: 引入微前端 (Micro-frontends)。
- **原因**: 多团队并行开发，独立部署需求。
## 3. 详细设计 (Detailed Design)
### 3.1 目录结构规范
```text
src/
├── app/ # 路由与页面入口 (Next.js style)
├── features/ # 业务功能模块 (按领域划分)
│ ├── user/
│ │ ├── components/
│ │ ├── hooks/
│ │ └── api.ts
├── shared/ # 共享资源 (UI Kit, Utils, Types)
├── infra/ # 基础设施 (HTTP Client, Auth, Logger)
└── main.tsx
```
### 3.2 核心模块设计
#### 3.2.1 [模块名称，如：通用数据表格]
- **功能描述**: 支持虚拟滚动、动态列配置、服务端排序。
- **组件层级**:
- `DataTable` (容器)
- `TableHeader` (配置渲染)
- `VirtualRow` (性能优化核心)
- **关键 Props 接口**:
```typescript
interface DataTableProps {
data: T[];
columns: ColumnDef[];
remotePagination?: boolean;
// ...
}
```
### 3.3 状态管理与数据流
- **服务器状态**: 使用 `TanStack Query` 管理，配置缓存时间 (staleTime: 5min)。
- **全局客户端状态**: 使用 `Zustand` 管理用户信息、主题设置。
- **表单状态**: 使用 `React Hook Form` 避免不必要的重渲染。
### 3.4 API 接口规范
- **通信协议**: HTTPS + JSON (或 GraphQL/Protobuf if needed).
- **错误处理标准**: 统一拦截 HTTP 4xx/5xx，转换为前端 Toast 提示。
- **Mock 方案**: 开发环境使用 `MSW (Mock Service Worker)` 拦截请求。
## 4. 非功能性设计 (Non-Functional Requirements)
### 4.1 性能优化策略
- **代码分割**: 路由级懒加载 + 大组件动态 import。
- **资源优化**: 图片自动转为 WebP/AVIF，字体子集化。
- **渲染优化**: 列表虚拟化，复杂计算移至 Web Worker。
- **指标目标**:
- LCP < 1.5s
- INP < 100ms
- Bundle Size (Gzip) < 300KB (Initial)
### 4.2 安全性设计
- **XSS 防护**: 框架默认转义，禁止使用 `dangerouslySetInnerHTML` (除非经过 DOMPurify)。
- **CSRF 防护**: 双重提交 Cookie 或 SameSite 策略。
- **敏感数据**: 前端不存储明文密码/Payment Info。
### 4.3 兼容性与 Accessibility
- **浏览器支持**: Chrome Last 2, Safari Last 2, Edge Last 2 (不兼容 IE11)。
- **无障碍 (A11y)**: 遵循 WCAG 2.1 AA 标准，所有图片有 Alt 文本，支持键盘导航。
## 5. 工程化与 DevOps
### 5.1 代码规范
- **Lint**: ESLint (Flat config) + Prettier + Biome (可选).
- **Git Hook**: Husky + Lint-staged (提交前自动修复格式)。
- **Commit 规范**: Conventional Commits (`feat:`, `fix:`, `chore:`).
### 5.2 测试策略
| 测试类型 | 工具 | 覆盖率目标 | 重点范围 |
| :----------- | :----------------------- | :------------ | :------------------- |
| **单元测试** | Vitest + Testing Library | > 80% | Utils, Hooks, 纯组件 |
| **E2E 测试** | Playwright | 核心链路 100% | 登录、下单、支付流程 |
| **视觉回归** | Percy / Chromatic | - | UI 组件库变更 |
### 5.3 CI/CD 流水线
1. **Install & Lint**: 安装依赖，运行静态检查。
2. **Test**: 运行单测和 E2E。
3. **Build**: 生产环境构建。
4. **Deploy**:
- Dev -> 自动部署到 Preview 环境。
- Main -> 自动部署到 Staging，人工确认后 Production。
## 6. 风险评估与应对 (Risk Management)
| 风险点 | 可能性 | 影响程度 | 应对方案 |
| :---------------------- | :----- | :------- | :----------------------------------------------- |
| 第三方地图 API 配额不足 | 中 | 高 | 建立本地缓存层，降级为静态图 |
| 旧版 iOS Safari CSS Bug | 高 | 中 | 引入 PostCSS 插件自动添加 Polyfill，准备降级样式 |
| 大列表导致页面卡顿 | 中 | 高 | 强制实施虚拟滚动方案，并在 PoC 阶段验证 |
## 7. 附录 (Appendix)
- [UI 设计稿链接 (Figma)]
- [API 文档链接 (Swagger)]
- [相关技术调研文章链接]
### 使用建议：
1. **灵活剪裁**：对于小型功能迭代，可以只保留“3. 详细设计”和“4. 非功能性设计”中的关键点；对于大型重构或新项目，请完整填写。
2. **图表胜过文字**：尽量使用 Mermaid 语法直接在 Markdown 中绘制流程图、时序图和架构图，保持文档的可维护性。
3. **活文档**：设计文档不是写完就扔的，随着开发过程中的变更，务必同步更新文档（特别是 ADR 部分），否则它会迅速贬值。
|
