前端技术札记 | BaiQiang

Appearance

前端架构设计最佳实践指南 ​

前端架构设计不仅仅是代码的组织，它是一套解决复杂性、提高可维护性、确保可扩展性的系统性方案。好的架构能让团队在业务高速增长时，依然保持较低的开发成本。

一、 什么是前端架构设计？ ​

前端架构可以拆解为以下四个核心维度：

  1. 代码组织 (Code Organization)：目录结构、文件命名规范。
  2. 模块化与组件化 (Modularity)：如何拆分组件，如何实现高复用、低耦合。
  3. 数据流管理 (State Management)：全局状态与局部状态的边界，数据的单向流动。
  4. 工程化支撑 (Infrastructure)：构建工具、CI/CD、监控、规范校验。

二、 如何做到好的架构设计？（核心原则） ​

1. 关注点分离 (Separation of Concerns) ​

  • UI 与 业务逻辑分离：组件只负责渲染，逻辑交给 Hook 或 Service 层。
  • 视图层与数据层分离：前端不仅仅是画页面，还要处理 API 适配、数据缓存。

2. 高内聚，低耦合 (High Cohesion, Low Coupling) ​

  • 单一职责：一个组件或函数只做一件事。
  • 模块独立性：修改 A 模块不应该导致不相关的 B 模块崩溃。

3. 可预测性 (Predictability) ​

  • 统一的数据流：避免双向绑定带来的混乱，提倡单向数据流（如 React 的 props 传递）。
  • 清晰的命名：看到文件名就知道它的作用。

三、 前端架构最佳实践 ​

1. 目录结构设计 (Folder Structure) ​

建议采用功能模块 (Feature-based) 而非单纯的文件类型组织：

text
src/
  components/     # 通用基础组件（Button, Input）
  features/       # 业务功能模块
    auth/         # 登录模块
      components/ # 登录专用组件
      hooks/      # 登录逻辑
      services/   # API 请求
      types/      # 类型定义
  hooks/          # 全局通用 Hooks
  services/       # 全局 API/基础库封装
  store/          # 全局状态管理
  utils/          # 纯工具函数

2. 状态管理策略 ​

  • 本地状态优先：能用 useState 解决的不要放进全局 Store。
  • 服务端状态与客户端状态分离：使用 React Query 或 SWR 处理接口数据，Store 只存 UI 交互状态（如主题、用户信息）。

3. 组件拆分规范 ​

  • 容器组件 (Container)：处理数据请求、逻辑。
  • 展示组件 (Presentational)：只负责 UI，通过 props 接收数据和回调。
  • 逻辑提取：复杂的逻辑必须提取到独立的 useHook 中，方便测试。

4. 类型安全 (TypeScript) ​

  • 架构设计的灵魂。必须定义清晰的 Interface 和 Type，消灭 any。
  • 后端接口数据应通过类型定义形成约束。

5. 样式架构 (Styling) ​

选择一致的样式方案是架构稳定的基石。

  • 方案选择：推荐 Tailwind CSS（原子化、生产力高）或 CSS Modules（作用域隔离）。
  • 规范：禁止使用内联样式（除动态计算外），建立统一的 Design Tokens（颜色、间距、字号）。

6. API 交互层 (Networking) ​

不要在组件中直接调用 fetch 或 axios。

  • 适配层：建立 services 层处理 API 请求、异常拦截和数据转换（Data Transformation）。
  • 统一处理：全局处理 401（未授权）、500（服务器错误）等状态码。

四、 进阶架构方案 ​

1. Monorepo (单仓多包) ​

当项目变得庞大或有多个关联项目（如：后台、前台、移动端、共享组件库）时，建议使用 Monorepo。

  • 工具推荐：pnpm workspaces + Turborepo。
  • 优势：代码共享简单、依赖版本统一、一次提交跨项目修改。

2. 微前端 (Micro Frontends) ​

适用于超大型团队协作，将巨型应用拆分为多个独立运行的微应用。

  • 技术选型：Module Federation (Webpack 5)、qiankun、wujie。
  • 注意：除非团队规模极大且项目确实需要独立部署，否则不要轻易引入，会增加系统复杂性。

五、 性能与安全最佳实践 (架构层面) ​

1. 性能优化策略 ​

  • 路由懒加载 (Code Splitting)：基于路由拆分代码包，减少首屏体积。
  • 静态资源优化：在架构中集成 CDN 自动上传、图片 WebP 转换、Gzip/Brotli 压缩。
  • 预加载策略：利用 prefetch/preload 在空闲时间加载次屏资源。

2. 安全防御 ​

  • XSS 防御：利用框架自带的转义机制，严格校验 dangerouslySetInnerHTML。
  • 敏感信息脱敏：不在前端存储敏感 Key，环境变量区分环境（.env）。
  • 内容安全策略 (CSP)：通过 HTTP 头部限制资源加载来源。

六、 测试与监控体系 ​

1. 测试金字塔 ​

  • 单元测试 (Unit Tests)：针对 utils 和纯逻辑 Hook (Vitest/Jest)。
  • 集成测试 (Integration Tests)：针对核心业务流程、关键组件交互。
  • E2E 测试 (End-to-End)：针对主路径（如登录、下单）进行模拟用户操作 (Playwright/Cypress)。

2. 异常监控与日志 ​

  • 错误边界 (Error Boundary)：在架构顶层捕获 UI 崩溃，展示友好提示而非白屏。
  • 全链路监控：集成 Sentry 或自定义日志平台，捕获 JS 错误、API 异常、资源加载失败。

七、 包容性与全球化 (Inclusive & Global) ​

1. 国际化 (i18n) ​

即使目前只有中文版，架构设计时也应预留 i18n 接口。

  • 文案分离：所有 UI 文本不硬编码，通过 t('key') 调用。
  • 适配：考虑不同语言的长度对布局的影响。

2. 无障碍 (Accessibility/A11y) ​

  • 语义化 HTML：正确使用 nav, main, aside 等标签。
  • ARIA 属性：为复杂组件提供必要的辅助说明。

七、 进阶架构思想：DDD 与 整洁架构 ​

1. 领域驱动设计 (DDD) 在前端的应用 ​

大型复杂系统（如 ERP、CRM）应引入 DDD。

  • 核心概念：
    • 领域模型 (Domain Model)：不仅是 API 数据结构，而是包含业务规则的对象。
    • 防腐层 (ACL)：通过适配器（Adapter）隔离后端 API 变动，确保前端核心逻辑的稳定性。

2. 整洁架构 (Clean Architecture) ​

  • 依赖倒置：高层逻辑（业务）不应依赖低层实现（UI/API）。
  • 结构分层：
    • Domain 层：核心业务实体与规则（纯 JS/TS）。
    • Use Cases 层：具体业务流程逻辑。
    • Adapters 层：接口适配、UI 组件。

八、 架构治理 (Governance) ​

1. 架构决策记录 (ADR) ​

重要的架构变更（如从 Webpack 换到 Vite）应记录 ADR 文件。

  • 记录内容：背景、可选方案、最终选择的原因、后果。

2. 文档化 ​

  • README：每个 Feature 目录下都应有简单的说明文档。
  • Storybook：为组件库建立可视化文档，方便前后端和 UI 沟通。

九、 环境与构建策略 (Environment & Build) ​

1. 多环境管理 ​

架构必须支持一套代码在多个环境（Dev, Staging, Prod）运行。

  • 构建时变量：使用 .env.development / .env.production 管理 API 地址等配置。
  • 运行时配置：对于需要“一次构建，到处运行”的场景，采用 window.config.js 等外部挂载方式。

2. 现代渲染模式 ​

根据业务选择合适的渲染架构：

  • SPA (Single Page App)：交互重的后台管理系统。
  • SSR/SSG (Next.js/Nuxt)：对 SEO 和首屏性能要求高的门户、电商页面。

十、 依赖治理与安全 (Dependency & Security) ​

1. 依赖选择原则 ​

  • 稳定性优先：优先选择社区活跃、下载量大、Issue 处理及时的库。
  • 体积敏感：使用 Bundle Analyzer 监控第三方库大小，避免引入巨型库（如 moment.js 换成 dayjs）。

2. 供应链安全 ​

  • 版本锁定：必须提交 pnpm-lock.yaml 或 package-lock.json。
  • 漏洞扫描：在 CI 中集成 npm audit 或 Snyk，防止引入有已知漏洞的包。

十一、 开发者体验 (Developer Experience/DX) ​

1. Mock 方案 ​

实现前后端并行开发的关键。

  • 推荐：MSW (Mock Service Worker)，在 Service Worker 层拦截请求，最接近真实网络环境且不侵入业务代码。

2. 本地化脚本 ​

  • 编写简单的 scripts，一键完成“环境检查 -> 依赖安装 -> 启动开发服务器”。

Powered by VitePress + GitHub Pages

Copyright © 2026 BaiQiang