架构设计与模式

1.1 什么是好架构？

好的架构不是一个「终极正确」的形态，而是让系统在当前阶段以可接受的成本应对预期内的变化。判断标准只有一条：需求的变更速度 vs 改动的成本——架构的价值就是让「改动成本的增长曲线」比「系统复杂度」平缓。

1.2 架构演进的真实路径（前端视角）

1. 阶段一：单文件——HTML 里写 JS，一切简单直接，改动成本低，但规模一上来就失控。
2. 阶段二：组件化——React/Vue 组件拆分，UI 复用有了抓手，但业务逻辑开始混进组件。
3. 阶段三：分层——展示层 / 业务层 / 数据层分离，状态管理工具上场，组件变薄。
4. 阶段四：模块化 + Monorepo——多个应用共享基础设施（设计系统、请求层、工具库），用 workspace 管理依赖。
5. 阶段五：微前端（可选）——多团队独立交付、独立技术栈，用 Module Federation 等手段组合。

2.1 S —— 单一职责原则（SRP）

一个模块只应该有一个「改变的理由」。判断方法：给这个模块列「它会被哪些原因修改」，超过一个就该拆。

// 反例：一个组件做了四件事——加载数据、渲染列表、过滤、导出 CSV
function UserListPage() {
  const [users, setUsers] = useState([])          // ① 数据获取
  const [keyword, setKeyword] = useState('')        // ② 搜索
  const filtered = users.filter(u => u.name.includes(keyword))

  const handleExport = () => {                    // ③ CSV 导出（另一个完全无关的职责）
    const csv = users.map(u => `${u.name},${u.email}`).join('\n')
    download(csv)
  }
  return <div>{filtered.map(u => <UserRow key={u.id} user={u} />)}</div>
}

// 正例：拆分——自定义 Hook 管数据，纯函数管过滤，工具函数管导出，组件只做组装
function useUsers() { /* 数据获取逻辑 */ }
export function filterByName(users: User[], keyword: string): User[] { /* 纯逻辑，可单测 */ }
export function toCsv(rows: User[]): string { /* 纯逻辑，可单测 */ }
function UserListPage() {
  const { users } = useUsers()
  const filtered = filterByName(users, keyword)
  return /* 纯渲染 */
}

2.2 O —— 开闭原则（OCP）

对扩展开放，对修改关闭：加新功能时尽量「新增代码」，而不是「改老代码」。前端最常见的落地方式：策略模式 + 配置表。

// 反例：加一种支付方式就要改 if 链
function pay(order: Order, method: string) {
  if (method === 'wechat') { wechatPay(order) }
  else if (method === 'alipay') { alipayPay(order) }
  else if (method === 'card') { cardPay(order) }
  throw new Error('unknown method')
}

// 正例：策略注册表——新增支付方式 = 新增一个文件，不改 pay 本体
type PayStrategy = { key: string; execute: (order: Order) => Promise<void> }

const strategies: Record<string, PayStrategy> = {
  wechat: { key: 'wechat', execute: wechatPay },
  alipay: { key: 'alipay', execute: alipayPay },
  card:   { key: 'card',   execute: cardPay },
}

async function pay(order: Order, method: string) {
  const s = strategies[method]
  if (!s) throw new Error('unknown method')
  await s.execute(order)
}

再加一个「境外卡」？新增一个策略对象注册进去即可，pay 函数一行不用改。

2.3 L —— 里氏替换原则（LSP）

子类型必须能替换父类型而不破坏行为。前端最实用的版本：「继承/扩展出来的东西，必须遵守基类定下的约定」。违反 LSP 的经典案例：正方形继承长方形（宽高独立设置会让面积逻辑出错）、抛「这个子类不支持」异常的基类方法。

// 反例：ErrorBoundary 吞掉所有错误，包括「不该吞」的
class AllErrorBoundary extends React.Component {
  componentDidCatch(error) { return '发生错误' }   // 连致命错误也吞，页面假死
}

// 正例：区分可恢复/不可恢复，把决定权交还给调用方
class ErrorBoundary extends React.Component {
  componentDidCatch(error) {
    if (error instanceof FatalError) { throw error }   // 致命错误继续抛
    this.props.onRecover?.()
    return '部分功能不可用'
  }
}

2.4 I —— 接口隔离原则（ISP）

不要强迫调用方依赖它不需要的东西。前端表现：组件 props 设计、API 返回类型设计、context 拆分。

// 反例：一个巨型 User 对象传给只显示名字的组件——组件被「无关字段」耦合
<UserCard user={user} />   // UserCard 其实只需要 name 和 avatar

// 正例：按需取字段，组件只声明自己需要的
type UserCardProps = { name: string; avatarUrl?: string }
<UserCard name={user.name} avatarUrl={user.avatarUrl} />

同理：context 拆成多个小 context（主题、语言、用户），避免任何组件被一个大 context 绑架；接口返回类型不要直接复用内部数据模型，按页面需求裁剪。

2.5 D —— 依赖倒置原则（DIP）

高层模块不依赖低层模块，两者都依赖抽象。前端版：业务逻辑不直接 import 具体的 fetch/axios，而是依赖「仓库接口」，实现可以替换（真实 API / Mock / 本地存储）。这正是上一章测试能轻松替换依赖的根基。

// 定义抽象：数据仓库接口（依赖倒置的「抽象」）
export interface UserRepository {
  getUsers(): Promise<User[]>
  getUserById(id: number): Promise<User | null>
}

// 低层实现 A：真实 API
export class HttpUserRepository implements UserRepository {
  async getUsers() { const r = await fetch('/api/users'); return r.json() }
}

// 低层实现 B：内存 Mock（测试 / 演示用）
export class MemoryUserRepository implements UserRepository {
  private data = [{ id: 1, name: 'Tom' }]
  async getUsers() { return this.data }
}

// 高层逻辑只认接口，不认实现
function getUserCount(repo: UserRepository) {
  return repo.getUsers().then(us => us.length)
}

3.1 推荐的分层结构（可裁剪）

src/
├── app/            // 应用组装层：路由、Provider、布局、全局样式（依赖所有层）
├── pages/          // 页面级组件：一页一个文件，只做「组装」
├── features/       // 业务功能域：按业务划分（auth / cart / order），各自私有组件+hooks+api
├── shared/         // 共享基础设施：UI 组件库、请求封装、工具函数、常量（被所有层依赖，不依赖任何业务）
│   ├── components/
│   ├── hooks/
│   ├── api/        // 对后端接口的封装，统一错误处理/鉴权/取消
│   └── utils/
└── types/          // 全局类型定义（DTO、领域模型）

两条铁律：

• 依赖方向从上到下：app → pages → features → shared，禁止 shared 依赖 features，禁止 features 之间互相 import（要共享就下沉到 shared）。
• features 自治：一个 feature 的内部（组件、hooks、API、状态）自己管，对外只暴露「页面入口」，这样砍功能、换实现都不波及其他域。

3.2 数据流方向：单向数据流是前端的「分层」

状态管理（阶段六）解决的是「状态放哪」，分层架构解决的是「数据往哪流」。理想的流转：

用户操作 → 事件 → 业务逻辑（纯函数/Hook）→ 状态更新 → 视图渲染 → 用户看到
     ↓（需要数据时）
  api 层请求 → 数据转换（DTO → 领域模型）→ 进入状态

4.1 创建型：工厂 / 单例

// 工厂模式：把「创建对象的细节」藏起来
// 比如按类型创建不同图表配置
function createChartConfig(kind: 'line' | 'bar' | 'pie'): ChartConfig {
  const base = { animation: true, responsive: true }
  switch (kind) {
    case 'line': return { ...base, type: 'line', smooth: true }
    case 'bar':  return { ...base, type: 'bar', stacked: false }
    case 'pie':  return { ...base, type: 'pie', donut: false }
  }
}

// 单例模式：全局唯一实例（但注意：模块级导出本身就是单例，通常不需要 class）
// ES Module 天然单例——真正需要手动单例的是「避免重复初始化」的场景
let socket: WebSocket | null = null
export function getSocket(): WebSocket {
  if (!socket || socket.readyState === WebSocket.CLOSED) {
    socket = new WebSocket('wss://api.example.com/ws')
  }
  return socket
}

4.2 结构型：适配器 / 装饰器

// 适配器模式：统一「长得不一样但语义相同」的接口
// 例：不同后端接口返回的日期格式不一样，适配成统一格式
interface OrderDTO { create_time: string }     // 后端 A：'2026-08-20 09:00'
interface OrderDTO2 { createdAt: number }    // 后端 B：时间戳

function adaptOrder(raw: OrderDTO | OrderDTO2): Order {
  if ('create_time' in raw) return { id: raw.id, createdAt: new Date(raw.create_time) }
  return { id: raw.id, createdAt: new Date(raw.createdAt) }
}

// 装饰器模式（函数式版本）：给函数加能力而不改它
function withRetry<T>(fn: () => Promise<T>, times = 3): () => Promise<T> {
  return async () => {
    let lastErr: unknown
    for (let i = 0; i < times; i++) {
      try { return await fn() } catch (e) { lastErr = e }
    }
    throw lastErr
  }
}
const loadWithRetry = withRetry(loadData)   // 原函数没动，能力变强了

4.3 行为型：策略 / 观察者（发布订阅）/ 状态机

// 策略模式已在 SOLID-O 里演示（支付方式注册表），这里演示观察者

// 观察者/发布订阅：事件的发布与订阅解耦（EventEmitter 是浏览器原生实现）
type Handler = (payload: unknown) => void

class Bus {
  private map = new Map<string, Handler[]>()
  on(event: string, h: Handler) { const arr = this.map.get(event) ?? []; arr.push(h); this.map.set(event, arr) }
  off(event: string, h: Handler) { this.map.set(event, (this.map.get(event) ?? []).filter(x => x !== h)) }
  emit(event: string, payload?: unknown) { (this.map.get(event) ?? []).forEach(h => h(payload)) }
}

// 状态机：把「一堆 if」变成「状态 × 事件」的转移表——处理复杂流程的利器
// 例：订单状态机
type State = 'created' | 'paid' | 'shipped' | 'done' | 'cancelled'
type Event = 'PAY' | 'SHIP' | 'COMPLETE' | 'CANCEL'

const transitions: Record<State, Partial<Record<Event, State>>> = {
  created:   { PAY: 'paid', CANCEL: 'cancelled' },
  paid:      { SHIP: 'shipped', CANCEL: 'cancelled' },
  shipped:   { COMPLETE: 'done' },
  done:      {},
  cancelled: {},
}

function transition(state: State, event: Event): State {
  const next = transitions[state][event]
  if (!next) throw new Error(`非法转移: ${state} + ${event}`)
  return next
}

4.4 React 特有模式：Render Props / HOC / 自定义 Hook

三者都是「逻辑复用」的手段，但定位不同：

// 自定义 Hook 是 React 生态最重要的「设计模式」
function useDebouncedValue<T>(value: T, delay = 300): T {
  const [debounced, setDebounced] = useState(value)
  useEffect(() => {
    const t = setTimeout(() => setDebounced(value), delay)
    return () => clearTimeout(t)
  }, [value, delay])
  return debounced
}

// 组合出更大粒度的 Hook：搜素 + 防抖 + 请求
function useSearch<T>(query: string, fetcher: (q: string) => Promise<T>) {
  const debounced = useDebouncedValue(query, 300)
  const [data, setData] = useState<T | null>(null)
  const [loading, setLoading] = useState(false)
  useEffect(() => {
    if (!debounced) { setData(null); return }
    setLoading(true)
    fetcher(debounced).then(setData).finally(() => setLoading(false))
  }, [debounced, fetcher])
  return { data, loading }
}

5.1 限界上下文（Bounded Context）

一个词在业务里不同场景含义不同。比如「订单」在下单域（含购物车明细）和售后域（含退款状态）是完全不同的模型。强行统一成一个「大订单模型」会让两端都被对方的概念污染。前端落地点：features 目录就是你的限界上下文——每个 feature 有自己的模型、自己的 api 封装、自己的状态，不跨域共享模型。

5.2 实体 / 值对象 / 聚合（简化版）

// 值对象：不可变 + 值相等
class Money {
  constructor(readonly amount: number, readonly currency: 'CNY' | 'USD') {}
  add(other: Money): Money {           // 返回新对象，不修改自身
    if (other.currency !== this.currency) throw new Error('币种不一致')
    return new Money(this.amount + other.amount, this.currency)
  }
  equals(other: Money): boolean {
    return this.amount === other.amount && this.currency === other.currency
  }
}

// 聚合根：订单只能通过方法修改，外部碰不到内部数组
class Order {
  private items: OrderItem[] = []
  addItem(item: OrderItem) {
    if (this.status !== 'created') throw new Error('已提交的订单不可修改')
    this.items.push(item)
  }
  total(): Money { return this.items.reduce(...) }
}

6.1 为什么需要 Monorepo

• 共享代码：多个前端应用（管理后台 / C 端 / 商家端）共用设计系统、请求层、工具库——不共用就复制粘贴，改 bug 要改三遍。
• 原子提交：改了公共库 + 使用方，一次提交一起变，不会出现「库升了但引用方没跟上」的中间状态。
• 统一工具链：一套 lint / test / build / CI 配置管理所有包。

6.2 pnpm workspace + Turborepo 实战

# pnpm-workspace.yaml —— 声明工作区
packages:
  - apps/*          // 应用：web、admin、docs
  - packages/*      // 共享包：ui、utils、request、config

// apps/web/package.json —— 用 workspace: 协议引用本地包
{
  "dependencies": {
    "@company/ui": "workspace:*",
    "@company/request": "workspace:*"
  }
}

// turbo.json —— 定义构建/测试的缓存与调度
{
  "tasks": {
    "build":   { "dependsOn": ["^build"], "outputs": ["dist/**"] },
    "test":    { "dependsOn": ["^build"] },
    "lint":    { "dependsOn": ["^build"] }
  }
}
// 运行：turbo run build --filter=@company/web（只构建 web 及其依赖）

7.1 微前端解决的真问题

• 多团队独立交付：不同团队不同节奏发版，互不阻塞。
• 遗留系统渐进改造：老系统（jQuery）和新系统（React）共存，一个模块一个模块迁移，不用推翻重来。
• 技术栈异构：确实需要不同栈并存（极少数情况）。

7.2 主流方案对比

8.1 技术选型五步法

1. 明确问题：我们在解决什么痛点？不解决它会怎样？
2. 列候选：3 个以内，别把所有流行库都拉进来比。
3. 定评估维度并打分：社区活跃度 / 团队熟悉度 / 学习成本 / 长期维护性 / 与现有栈契合度。给每个维度加权。
4. 做小样验证：用候选技术各做一个 2～3 天的 PoC（Proof of Concept，概念验证），验证「文档里吹的」在真实场景是否成立。
5. 写 ADR 存档：记录决策、理由、备选、代价。三个月后有人问「为什么用 X」，直接看文档，不用考古。

8.2 ADR（Architecture Decision Record）模板

# ADR-0017：状态管理从 Redux 迁移到 Zustand

状态：已接受（2026-08-20，评审人：王工/李工）

背景
业务页面大量使用「局部状态 + 少量全局状态」模式，Redux 的样板代码
（action 类型、reducer、selector 的重复声明）占开发成本约 15%，
且团队新人上手周期长。我们不需要时间旅行调试、跨组件中间件等高级特性。

决策
新业务模块使用 Zustand；存量 Redux 代码不重写，随迭代自然替换。

理由
- Zustand 样板代码减少约 70%，set/get 心智模型更简单
- 支持 selector + useShallow，性能优化零成本
- 无 Provider 包裹，组件测试更简单
- 可持久化中间件满足当前需求
- 团队 4 人已有 Zustand 实战经验（1 个季度）

备选方案
- Jotai：原子模型更细，但团队不熟，且我们无「极细粒度共享状态」需求
- 维持 Redux：无迁移成本，但样板代码问题持续存在

代价
- 两套状态方案并存 2～3 个季度，新增代码需遵循「新用 Zustand」约定
- 存量 Redux 维护者只剩 1 人，需在交接文档中注明

验证
试点模块（商品详情页）迁移后，新增代码行数下降 30%，
测试用例不变的前提下测试时间下降 25%。

• 为「未来可能」的需求做架构：YAGNI（You Aren't Gonna Need It）——90% 的「可能需求」永远不会来，架构复杂度却留下了。为当下明确需求设计，为未来留「可演进性」而非「提前实现」。
• 抽象过早：只有一份实现时抽象 = 猜需求。等第二、三个真实调用方出现再抽象（Rule of Three）。
• 跨层直连：组件直接 fetch、直接改全局 state，绕过分层。规矩：依赖方向只能向下。
• 共享可变状态：两个模块通过「全局变量」通信，改起来互相踩。解法：事件总线（解耦）或显式状态管理。
• 巨型组件：500 行的组件 = 5 个职责 + 0 个测试。解法：按 SRP 拆 Hook + 纯函数 + 子组件。
• 用继承组织业务：JS 的继承链三层以上基本失控。解法：组合优先（props/Hook/依赖注入）。
• 不写 ADR：三个月后团队没人知道「为什么这么设计」，只能继续在错误地基上加盖。解法：每个架构决策一个 markdown。
• 为微前端而微前端：单团队单体应用上微前端，复杂度翻倍、性能下降。解法：先回答组织问题。
• Monorepo 依赖提升失控：不同包依赖同一个库的不同版本，构建产物膨胀。解法：统一版本策略（shared deps 放根、pnpm.overrides 强制版本）。
• 架构评审流于形式：评审只看 PPT 不看代码、不验证假设。解法：ADR + PoC 演示 + 上线后回访数据。

项目 A：给「电商管理后台」做架构重构（推荐）

1. 找一个你写过的（或开源的）后台项目，按本章分层结构重构：app / pages / features / shared 四层，依赖方向只向下。
2. 把散落的 fetch 全部收敛到 shared/api 层，统一错误处理与鉴权。
3. 挑一个复杂业务域（如订单），用「状态机」重写其状态流转，非法转移抛错。
4. 把「订单」相关的模型、组件、状态抽成独立 feature（限界上下文实践）。
5. 为这次重构写一份 ADR，含背景、决策、理由、备选、代价、验证数据。

项目 B：从零设计一个「插件化」的富文本编辑器

1. 用「核心 + 插件」架构：核心只做文档模型 + 渲染 + 命令总线，插件（加粗/表格/图片）通过注册表接入（OCP 实战）。
2. 命令总线用「策略注册表」实现（可撤销栈 + 命令模式）。
3. 文档模型用「状态机」管理（只读/编辑/脏标记）。
4. 每个插件独立成模块，带自己的测试；核心不依赖任何插件。
5. 写 ADR 说明「为什么插件用注册表而不是继承」。