前端架构设计（Frontend Architecture）

为大型前端应用设计可扩展的架构——不是"用什么框架"，而是如何组织代码、划分模块、管理依赖，让项目在 2 年后还能维护。

触发场景

• 「新项目技术选型」「从零搭建前端架构」
• 「项目越来越乱」「不知道代码该放哪」「模块耦合严重」
• 「多团队协作」「微前端」「代码复用」
• 「技术债务」「重构策略」「如何避免架构腐化」

执行流程

1. 先搞清楚项目规模和约束

不要一上来就给"最佳实践"，先问清楚：

2. 项目结构设计

小型项目（\x3C 3 人，\x3C 6 个月）：

src/
├── components/       # 所有组件
├── pages/           # 路由页面
├── hooks/           # 自定义 hooks
├── utils/           # 工具函数
├── api/             # API 请求
└── types/           # 类型定义

中型项目（3-10 人，6 个月 - 2 年）：

src/
├── features/              # 按功能域划分
│   ├── auth/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── api/
│   │   ├── types.ts
│   │   └── index.ts      # 导出公共接口
│   ├── dashboard/
│   └── settings/
├── shared/                # 跨 feature 共享
│   ├── components/       # 通用组件（Button、Modal）
│   ├── hooks/
│   ├── utils/
│   └── types/
├── app/                   # 应用层（路由、布局、全局状态）
│   ├── routes/
│   ├── layouts/
│   └── providers/
└── lib/                   # 第三方库封装
    ├── axios.ts
    ├── react-query.ts
    └── analytics.ts

大型项目（10+ 人，2 年+）：

packages/                  # Monorepo
├── apps/
│   ├── web/              # 主应用
│   ├── admin/            # 管理后台
│   └── mobile/           # 移动端（可选）
├── features/             # 业务功能包
│   ├── auth/
│   ├── payment/
│   └── analytics/
├── ui/                   # 设计系统
│   ├── components/
│   ├── tokens/
│   └── themes/
├── shared/               # 共享工具
│   ├── utils/
│   ├── types/
│   ├── hooks/
│   └── api-client/
└── config/               # 共享配置
    ├── eslint/
    ├── tsconfig/
    └── tailwind/

3. 模块边界与依赖规则

分层架构（推荐）：

app/          # 应用层：路由、布局、全局状态
  ↓ 可以依赖
features/     # 功能层：业务逻辑
  ↓ 可以依赖
shared/       # 共享层：通用组件、工具
  ↓ 可以依赖
lib/          # 基础设施层：第三方库封装

依赖规则（用 ESLint 强制）：

// .eslintrc.js
{
  rules: {
    'no-restricted-imports': ['error', {
      patterns: [
        {
          group: ['@/features/*'],
          message: 'shared/ 不能依赖 features/'
        },
        {
          group: ['@/features/auth/*'],
          importNames: ['*'],
          message: 'features 之间不能直接依赖，通过 shared/ 或事件通信'
        }
      ]
    }]
  }
}

feature 之间的通信：

// ❌ 错：feature A 直接导入 feature B
import { useUserStore } from '@/features/auth/store'

// ✅ 对：通过 shared 层暴露接口
// shared/stores/user.ts
export { useUserStore } from '@/features/auth/store'

// 或用事件总线解耦
// shared/events.ts
export const eventBus = mitt()
// feature A
eventBus.emit('user:logout')
// feature B
eventBus.on('user:logout', handleLogout)

4. 代码分割策略

分割粒度的决策：

Next.js App Router 的分割：

// app/dashboard/page.tsx
import { Suspense } from 'react'
import dynamic from 'next/dynamic'

// 路由级自动分割，不需要手动 dynamic
export default function DashboardPage() {
  return \x3CDashboardContent />
}

// 大型图表库按需加载
const HeavyChart = dynamic(() => import('@/components/HeavyChart'), {
  loading: () => \x3CChartSkeleton />,
  ssr: false,  // 不在服务端渲染
})

// 低频功能懒加载
const ExportModal = dynamic(() => import('./ExportModal'))

Vite 的手动分包：

// vite.config.ts
export default {
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'vendor-react': ['react', 'react-dom', 'react-router-dom'],
          'vendor-ui': ['@radix-ui/react-dialog', '@radix-ui/react-dropdown-menu'],
          'vendor-charts': ['echarts', 'recharts'],
        }
      }
    }
  }
}

5. 技术选型决策框架

不要凭感觉选，用决策矩阵：

关键技术选型的决策点：

框架选择（React vs Vue vs Svelte）：

• 团队已有技能 > 框架本身优劣
• ToB 后台、数据密集 → React（生态最完善）
• 快速原型、小团队 → Vue（上手快）
• 性能极致要求 → Svelte（编译时优化）

状态管理（Zustand vs Redux vs Jotai）：

• 简单全局状态 → Zustand
• 复杂业务逻辑、需要中间件 → Redux Toolkit
• 原子化状态、细粒度更新 → Jotai

样式方案（Tailwind vs CSS Modules vs CSS-in-JS）：

• 快速开发、设计系统 → Tailwind
• 组件库、样式隔离 → CSS Modules
• 动态主题、运行时样式 → CSS-in-JS（Stitches/Panda）

6. 技术债管理

技术债的分类：

ADR（Architecture Decision Record）模板：

# ADR-001: 选择 Zustand 作为状态管理方案

## 状态
已决定

## 背景
项目需要全局状态管理，主要用于主题、用户信息、通知等 UI 状态。

## 决策
选择 Zustand，不用 Redux。

## 理由
- 代码量少（Redux 需要 action/reducer/selector，Zustand 直接 set）
- 性能好（细粒度订阅，不需要 reselect）
- 学习曲线低（团队新人多）
- 不需要 Redux 的中间件生态（没有复杂异步逻辑）

## 后果
- 正面：开发效率高，代码简洁
- 负面：如果未来需要时间旅行调试，需要额外配置
- 缓解：用 Redux DevTools 扩展监控 Zustand

7. 渐进式重构策略

什么时候重构，什么时候重写：

绞杀者模式示例（微前端）：

旧应用（legacy.example.com）
  ├── /dashboard  → 保留
  ├── /settings   → 迁移到新应用
  └── /reports    → 迁移到新应用

新应用（app.example.com）
  ├── /settings   → 新架构实现
  └── /reports    → 新架构实现

Nginx 路由：
  /settings → app.example.com
  /reports  → app.example.com
  /*        → legacy.example.com

架构反模式

输出模板

## 前端架构方案

### 项目背景
- 团队规模：X 人
- 预期生命周期：X 年
- 性能要求：[ToB 后台 / ToC 高性能]
- 现有技术栈：[新项目 / 存量迁移]

### 技术选型
| 维度 | 方案 | 理由 |
|------|------|------|
| 框架 | React / Vue / Svelte | … |
| 状态管理 | Zustand / Redux / Jotai | … |
| 样式 | Tailwind / CSS Modules | … |
| 构建 | Vite / Next.js | … |

### 项目结构
[目录树 + 分层说明]

### 模块边界
- 依赖规则：[分层图]
- ESLint 规则：[no-restricted-imports 配置]

### 代码分割策略
- 路由级：每个页面一个 chunk
- 大型依赖：[列出需要单独分割的库]
- 懒加载：[列出低频功能]

### 技术债管理
- ADR 存放位置：docs/adr/
- 重构策略：[渐进式 / 绞杀者模式]