builder-pattern.md

name	metaframe-builder-pattern
category	engineering
description	构建器模式 | Code & Engineering

构建器模式

英文名: Builder Pattern
分类: 编码实践
作者: Gamma, Helm, Johnson, Vlissides, 1994
复杂度: beginner
成熟度: foundational
AI 相关: ❌ 否

简介

使用流式 API 逐步构建复杂对象，将构建过程与对象表示分离，支持多种表示形式

核心概念

• 逐步构建：构建器通过一系列命名 setter 调用积累配置，使每个参数的用途在调用点显式明确
• 流式接口：每个 setter 返回 Builder 实例，支持可读的方法链语法，读起来像自然语言（new PersonBuilder().name("Alice").age(30).build()）
• 构建与表示分离：Builder 将复杂的组装逻辑与产品类本身隔离，允许多个 Builder 实现生产不同的产品变体

使用步骤

1. 识别复杂对象：针对具有许多构造函数参数（尤其是可选参数）、伸缩式构造函数或需要多步初始化的类
2. 创建构建器类：实现一个单独的 Builder（通常是静态内部类），为每个可配置属性提供 setter 方法，每个方法返回 Builder 本身以支持链式调用
3. 在 build() 中添加验证：实现终结方法 build()，验证必填字段已设置，组装最终不可变对象，如违反前置条件则抛出异常
4. 使目标对象不可变：构造目标类使其只接受完全构建的 Builder 实例，将所有值存储为可通过 getter 访问的 final 字段
5. 引入 Director（可选）：为常用配置添加 Director 类，使客户端可以生产标准产品（如 buildMinimalConfig()、buildProductionConfig()）而无需重复步骤

适用场景

['一个类有四个或更多构造函数参数，尤其是其中几个是可选的，使调用点模糊且容易出错', '相同的构建过程应该生产不同的表示（如 HTML vs PDF 报告构建器）', '对象初始化需要特定的步骤顺序或验证逻辑，不能被绕过']

最佳实践

✅ 推荐做法

• 通过将所有字段存储为 final 并只提供 getter 使构建的产品不可变——构建器是唯一的变更点
• 在 build() 中验证字段组合而非在单个 setter 中，使验证在完整配置上运行一次
• 在 Builder 中为可选字段提供合理的默认值，使调用方只需指定与规范不同的内容

❌ 避免做法

• 不要对具有一两个必填字段的简单对象使用构建器——在普通构造函数更清晰的地方增加了不必要的繁文缛节
• 不要在 build() 调用后允许 Builder 重用而不明确重置；重用会导致产品实例之间意外的共享状态
• 不要跳过终结 build() 验证步骤——静默返回部分配置的对象比构建时的明确异常更糟糕

---

Sources: SDFrame (Software Design) MetaFrame: 💻 Code & Engineering / 编码与工程