Skip to content

Commit 0b494cb

Browse files
author
baiqiang
committed
feat: 首次提交，完成博客基础架构搭建
0 parents  commit 0b494cb

16 files changed

Lines changed: 3360 additions & 0 deletions

‎.github/workflows/deploy.yml‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
name: Deploy VitePress site to Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: pages
16+
cancel-in-progress: true
17+
18+
jobs:
19+
build:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- name: Checkout
23+
uses: actions/checkout@v4
24+
25+
- name: Setup Node.js
26+
uses: actions/setup-node@v4
27+
with:
28+
node-version: 18.20.4
29+
cache: npm
30+
31+
- name: Install dependencies
32+
run: npm ci
33+
34+
- name: Build site
35+
run: npm run docs:build
36+
env:
37+
GITHUB_REPOSITORY: ${{ github.repository }}
38+
39+
- name: Setup Pages
40+
uses: actions/configure-pages@v5
41+
42+
- name: Upload artifact
43+
uses: actions/upload-pages-artifact@v3
44+
with:
45+
path: docs/.vitepress/dist
46+
47+
deploy:
48+
needs: build
49+
runs-on: ubuntu-latest
50+
environment:
51+
name: github-pages
52+
url: ${{ steps.deployment.outputs.page_url }}
53+
steps:
54+
- name: Deploy to GitHub Pages
55+
id: deployment
56+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
node_modules/
2+
docs/.vitepress/cache/
3+
docs/.vitepress/dist/
4+
5+
# Drafts in content directory
6+
content/_*

‎content/frontend-architecture-best-practices.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
# 前端架构设计最佳实践指南
2+
3+
前端架构设计不仅仅是代码的组织，它是一套**解决复杂性、提高可维护性、确保可扩展性**的系统性方案。好的架构能让团队在业务高速增长时，依然保持较低的开发成本。
4+
5+
---
6+
7+
## 一、 什么是前端架构设计？
8+
9+
前端架构可以拆解为以下四个核心维度：
10+
11+
1. **代码组织 (Code Organization)**：目录结构、文件命名规范。
12+
2. **模块化与组件化 (Modularity)**：如何拆分组件，如何实现高复用、低耦合。
13+
3. **数据流管理 (State Management)**：全局状态与局部状态的边界，数据的单向流动。
14+
4. **工程化支撑 (Infrastructure)**：构建工具、CI/CD、监控、规范校验。
15+
16+
---
17+
18+
## 二、 如何做到好的架构设计？（核心原则）
19+
20+
### 1. 关注点分离 (Separation of Concerns)
21+
- **UI 与 业务逻辑分离**：组件只负责渲染，逻辑交给 Hook 或 Service 层。
22+
- **视图层与数据层分离**：前端不仅仅是画页面，还要处理 API 适配、数据缓存。
23+
24+
### 2. 高内聚，低耦合 (High Cohesion, Low Coupling)
25+
- **单一职责**：一个组件或函数只做一件事。
26+
- **模块独立性**：修改 A 模块不应该导致不相关的 B 模块崩溃。
27+
28+
### 3. 可预测性 (Predictability)
29+
- **统一的数据流**：避免双向绑定带来的混乱，提倡单向数据流（如 React 的 props 传递）。
30+
- **清晰的命名**：看到文件名就知道它的作用。
31+
32+
---
33+
34+
## 三、 前端架构最佳实践
35+
36+
### 1. 目录结构设计 (Folder Structure)
37+
建议采用**功能模块 (Feature-based)** 而非单纯的文件类型组织：
38+
```text
39+
src/
40+
components/ # 通用基础组件（Button, Input）
41+
features/ # 业务功能模块
42+
auth/ # 登录模块
43+
components/ # 登录专用组件
44+
hooks/ # 登录逻辑
45+
services/ # API 请求
46+
types/ # 类型定义
47+
hooks/ # 全局通用 Hooks
48+
services/ # 全局 API/基础库封装
49+
store/ # 全局状态管理
50+
utils/ # 纯工具函数
51+
```
52+
53+
### 2. 状态管理策略
54+
- **本地状态优先**：能用 `useState` 解决的不要放进全局 Store。
55+
- **服务端状态与客户端状态分离**：使用 `React Query` 或 `SWR` 处理接口数据，Store 只存 UI 交互状态（如主题、用户信息）。
56+
57+
### 3. 组件拆分规范
58+
- **容器组件 (Container)**：处理数据请求、逻辑。
59+
- **展示组件 (Presentational)**：只负责 UI，通过 props 接收数据和回调。
60+
- **逻辑提取**：复杂的逻辑必须提取到独立的 `useHook` 中，方便测试。
61+
62+
### 4. 类型安全 (TypeScript)
63+
- 架构设计的灵魂。必须定义清晰的 **Interface** 和 **Type**，消灭 `any`。
64+
- 后端接口数据应通过类型定义形成约束。
65+
66+
### 5. 样式架构 (Styling)
67+
选择一致的样式方案是架构稳定的基石。
68+
- **方案选择**：推荐 **Tailwind CSS**（原子化、生产力高）或 **CSS Modules**（作用域隔离）。
69+
- **规范**：禁止使用内联样式（除动态计算外），建立统一的 Design Tokens（颜色、间距、字号）。
70+
71+
### 6. API 交互层 (Networking)
72+
不要在组件中直接调用 `fetch` 或 `axios`。
73+
- **适配层**：建立 `services` 层处理 API 请求、异常拦截和数据转换（Data Transformation）。
74+
- **统一处理**：全局处理 401（未授权）、500（服务器错误）等状态码。
75+
76+
---
77+
78+
## 四、 进阶架构方案
79+
80+
### 1. Monorepo (单仓多包)
81+
当项目变得庞大或有多个关联项目（如：后台、前台、移动端、共享组件库）时，建议使用 Monorepo。
82+
- **工具推荐**：`pnpm workspaces` + `Turborepo`。
83+
- **优势**：代码共享简单、依赖版本统一、一次提交跨项目修改。
84+
85+
### 2. 微前端 (Micro Frontends)
86+
适用于超大型团队协作，将巨型应用拆分为多个独立运行的微应用。
87+
- **技术选型**：Module Federation (Webpack 5)、qiankun、wujie。
88+
- **注意**：除非团队规模极大且项目确实需要独立部署，否则不要轻易引入，会增加系统复杂性。
89+
90+
---
91+
92+
## 五、 性能与安全最佳实践 (架构层面)
93+
94+
### 1. 性能优化策略
95+
- **路由懒加载 (Code Splitting)**：基于路由拆分代码包，减少首屏体积。
96+
- **静态资源优化**：在架构中集成 CDN 自动上传、图片 WebP 转换、Gzip/Brotli 压缩。
97+
- **预加载策略**：利用 `prefetch`/`preload` 在空闲时间加载次屏资源。
98+
99+
### 2. 安全防御
100+
- **XSS 防御**：利用框架自带的转义机制，严格校验 `dangerouslySetInnerHTML`。
101+
- **敏感信息脱敏**：不在前端存储敏感 Key，环境变量区分环境（`.env`）。
102+
- **内容安全策略 (CSP)**：通过 HTTP 头部限制资源加载来源。
103+
104+
---
105+
106+
## 六、 测试与监控体系
107+
108+
### 1. 测试金字塔
109+
- **单元测试 (Unit Tests)**：针对 `utils` 和纯逻辑 Hook (Vitest/Jest)。
110+
- **集成测试 (Integration Tests)**：针对核心业务流程、关键组件交互。
111+
- **E2E 测试 (End-to-End)**：针对主路径（如登录、下单）进行模拟用户操作 (Playwright/Cypress)。
112+
113+
### 2. 异常监控与日志
114+
- **错误边界 (Error Boundary)**：在架构顶层捕获 UI 崩溃，展示友好提示而非白屏。
115+
- 全链路监控：集成 Sentry 或自定义日志平台，捕获 JS 错误、API 异常、资源加载失败。
116+
117+
---
118+
119+
## 七、 包容性与全球化 (Inclusive & Global)
120+
121+
### 1. 国际化 (i18n)
122+
即使目前只有中文版，架构设计时也应预留 i18n 接口。
123+
- **文案分离**：所有 UI 文本不硬编码，通过 `t('key')` 调用。
124+
- **适配**：考虑不同语言的长度对布局的影响。
125+
126+
### 2. 无障碍 (Accessibility/A11y)
127+
- **语义化 HTML**：正确使用 `nav`, `main`, `aside` 等标签。
128+
- **ARIA 属性**：为复杂组件提供必要的辅助说明。
129+
130+
---
131+
132+
## 七、 进阶架构思想：DDD 与 整洁架构
133+
134+
### 1. 领域驱动设计 (DDD) 在前端的应用
135+
大型复杂系统（如 ERP、CRM）应引入 DDD。
136+
- **核心概念**：
137+
- **领域模型 (Domain Model)**：不仅是 API 数据结构，而是包含业务规则的对象。
138+
- **防腐层 (ACL)**：通过适配器（Adapter）隔离后端 API 变动，确保前端核心逻辑的稳定性。
139+
140+
### 2. 整洁架构 (Clean Architecture)
141+
- **依赖倒置**：高层逻辑（业务）不应依赖低层实现（UI/API）。
142+
- **结构分层**：
143+
- **Domain 层**：核心业务实体与规则（纯 JS/TS）。
144+
- **Use Cases 层**：具体业务流程逻辑。
145+
- **Adapters 层**：接口适配、UI 组件。
146+
147+
---
148+
149+
## 八、 架构治理 (Governance)
150+
151+
### 1. 架构决策记录 (ADR)
152+
重要的架构变更（如从 Webpack 换到 Vite）应记录 ADR 文件。
153+
- **记录内容**：背景、可选方案、最终选择的原因、后果。
154+
155+
### 2. 文档化
156+
- **README**：每个 Feature 目录下都应有简单的说明文档。
157+
- **Storybook**：为组件库建立可视化文档，方便前后端和 UI 沟通。
158+
159+
---
160+
161+
## 九、 环境与构建策略 (Environment & Build)
162+
163+
### 1. 多环境管理
164+
架构必须支持一套代码在多个环境（Dev, Staging, Prod）运行。
165+
- **构建时变量**：使用 `.env.development` / `.env.production` 管理 API 地址等配置。
166+
- **运行时配置**：对于需要“一次构建，到处运行”的场景，采用 `window.config.js` 等外部挂载方式。
167+
168+
### 2. 现代渲染模式
169+
根据业务选择合适的渲染架构：
170+
- **SPA (Single Page App)**：交互重的后台管理系统。
171+
- **SSR/SSG (Next.js/Nuxt)**：对 SEO 和首屏性能要求高的门户、电商页面。
172+
173+
---
174+
175+
## 十、 依赖治理与安全 (Dependency & Security)
176+
177+
### 1. 依赖选择原则
178+
- **稳定性优先**：优先选择社区活跃、下载量大、Issue 处理及时的库。
179+
- **体积敏感**：使用 Bundle Analyzer 监控第三方库大小，避免引入巨型库（如 moment.js 换成 dayjs）。
180+
181+
### 2. 供应链安全
182+
- **版本锁定**：必须提交 `pnpm-lock.yaml` 或 `package-lock.json`。
183+
- **漏洞扫描**：在 CI 中集成 `npm audit` 或 `Snyk`，防止引入有已知漏洞的包。
184+
185+
---
186+
187+
## 十一、 开发者体验 (Developer Experience/DX)
188+
189+
### 1. Mock 方案
190+
实现前后端并行开发的关键。
191+
- **推荐**：**MSW (Mock Service Worker)**，在 Service Worker 层拦截请求，最接近真实网络环境且不侵入业务代码。
192+
193+
### 2. 本地化脚本
194+
- 编写简单的 `scripts`，一键完成“环境检查 -> 依赖安装 -> 启动开发服务器”。

‎content/frontend-engineering-guide.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# 前端工程化工具指南
2+
3+
前端工程化是指通过工具、规范和流程，将前端开发从“手工劳作”转变为“工业化生产”的过程。它的核心目标是**提高开发效率、降低维护成本、保证项目质量**。
4+
5+
---
6+
7+
## 一、 核心工具分类
8+
9+
### 1. 包管理工具 (Package Management)
10+
- **npm / Yarn**: 基础工具，必须掌握依赖安装、版本控制（lock文件）和脚本配置。
11+
- **pnpm (推荐)**: 目前大厂首选，采用内容寻址存储，速度极快且节省磁盘空间，支持单仓多包（Monorepo）。
12+
13+
### 2. 构建与打包工具 (Build Tools)
14+
- **Webpack**: 行业标准，功能最强。重点掌握：Loader与Plugin的区别、热更新原理、性能优化（Tree Shaking、分包）。
15+
- **Vite (热门)**: 开发体验极佳，利用原生ESM实现秒级启动。现代项目（如Vue3/React新项目）的首选。
16+
- **Rollup**: 主要用于类库（Library）打包，输出体积更小、更纯净。
17+
18+
### 3. 代码质量与规范 (Linting & Formatting)
19+
- **ESLint**: 强制执行代码风格和检测潜在Bug。
20+
- **Prettier**: 专注于代码格式化，解决团队协作中的缩进、分号等争议。
21+
- **Husky + lint-staged**: 在 Git Commit 前自动运行校验，确保不规范的代码无法提交。
22+
23+
### 4. 自动化测试 (Testing)
24+
- **Vitest / Jest**: 单元测试框架，掌握如何编写测试用例、Mock数据。
25+
- **Cypress / Playwright**: 端到端（E2E）测试，模拟用户真实操作。
26+
27+
### 5. 持续集成/持续部署 (CI/CD)
28+
- **GitHub Actions / GitLab CI**: 了解如何自动化构建、测试和发布流程。
29+
- **Docker / Nginx**: 了解容器化部署和前端静态资源的代理转发。
30+
31+
---
32+
33+
## 二、 进阶学习路径建议
34+
35+
### 第一阶段：基础夯实（1-2个月）
36+
- **目标**: 熟练使用 npm/pnpm 管理项目，配置简单的 ESLint 和 Prettier。
37+
- **行动**: 在现有项目中引入 Husky，确保每次提交代码都是整洁的。学习 Git 的高级用法（Rebase, Cherry-pick）。
38+
39+
### 第二阶段：构建进阶（2-4个月）
40+
- **目标**: 深入理解打包原理。
41+
- **行动**: 尝试从零配置一个 Webpack 项目（不使用脚手架），实现 CSS 处理、图片压缩、多环境切换。随后学习 Vite，对比两者的构建差异。
42+
43+
### 第三阶段：体系建设（4-6个月）
44+
- **目标**: 具备搭建企业级架构的能力。
45+
- **行动**:
46+
- 学习 **Monorepo** 架构（使用 pnpm + Turborepo/Nx）。
47+
- 掌握 **脚手架开发**：编写一个自己的 CLI 工具，自动生成项目模版。
48+
- 接入 **CI/CD 流水线**：在 GitHub 上配置 Action，实现代码推送后自动部署到服务器。
49+
50+
### 第四阶段：深度优化（长期）
51+
- **目标**: 解决复杂工程问题。
52+
- **行动**: 研究首屏加载优化、持久化缓存策略、构建速度提升（如使用 esbuild/swc 替代传统转译器）。
53+
54+
---
55+
56+
## 三、 工程化深度实践：脚手架与 CI/CD
57+
58+
### 1. 企业级脚手架开发 (CLI)
59+
不要只是用 `create-react-app`，精通者应能根据团队规范定制脚手架。
60+
- **核心能力**：
61+
- **交互式命令行**：使用 `inquirer` 或 `enquirer` 收集用户配置。
62+
- **模板引擎**：使用 `handlebars` 或 `ejs` 动态生成项目代码。
63+
- **自动集成**：一键配置 ESLint、Git Hooks、CI 工作流。
64+
65+
### 2. CI/CD 自动化流水线
66+
- **核心环节**：
67+
- **Lint & Test**：代码提交即触发静态检查与单元测试。
68+
- **Preview**：为每个 PR 自动生成预览环境。
69+
- **Release**：自动化版本更新（Standard Version）与 CHANGELOG 生成。
70+
- **Security Scan**：集成依赖漏洞扫描。
71+
72+
---
73+
74+
## 四、 核心能力总结
75+
1. **拥有自己的脚手架项目**: 能够体现对工具链的整合与定制能力。
76+
2. **底层原理的深度理解**: 深入学习 Webpack 构建流程或 Vite 运行机制。
77+
3. **性能监控与治理**: 实践如何接入监控工具（如 Sentry）并根据数据驱动工程改进。

‎docs/.vitepress/config.ts‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
import { defineConfig } from 'vitepress';
2+
3+
const repository = process.env.GITHUB_REPOSITORY;
4+
const repositoryName = repository?.split('/')[1] ?? '';
5+
const isUserOrOrgPagesRepo = repositoryName.endsWith('.github.io');
6+
const base = repository
7+
? isUserOrOrgPagesRepo
8+
? '/'
9+
: `/${repositoryName}/`
10+
: '/';
11+
12+
export default defineConfig({
13+
lang: 'zh-CN',
14+
title: '前端技术札记 | BaiQiang',
15+
description: 'BaiQiang 的个人前端技术博客，聚焦前端基础、工程化、性能优化与架构设计。',
16+
base,
17+
lastUpdated: true,
18+
cleanUrls: true,
19+
themeConfig: {
20+
logo: '/favicon.svg',
21+
nav: [
22+
{ text: '首页', link: '/' },
23+
{ text: '文章列表', link: '/posts/' },
24+
],
25+
search: {
26+
provider: 'local',
27+
},
28+
socialLinks: [
29+
{
30+
icon: 'github',
31+
link: repository ? `https://github.com/${repository}` : 'https://github.com/你的用户名/你的仓库名',
32+
},
33+
],
34+
footer: {
35+
message: 'Powered by VitePress + GitHub Pages',
36+
copyright: `Copyright © ${new Date().getFullYear()} BaiQiang`,
37+
},
38+
},
39+
sitemap: {
40+
hostname: repository
41+
? isUserOrOrgPagesRepo
42+
? `https://${repositoryName}/`
43+
: `https://${repository.split('/')[0]}.github.io/${repositoryName}/`
44+
: 'https://example.com/',
45+
},
46+
});

0 commit comments

Comments
 (0)