Step Builder(分步构建)模式在 Java 中的落地实践:以 java-design-patterns 仓库源码为例
Step Builder(分步构建)模式在 Java 中的落地实践:以 java-design-patterns 仓库源码为例
Step Builder(分步构建)是经典 Builder(构建者)模式的一种扩展,核心价值在于完全引导使用者完成对象创建,不给任何混淆的机会:在每一步只能看到"下一步该调用的方法",直到合适的时机,build() 方法才会出现在视野中,从而显著提升 API 的易用性与代码的可读性。本文以开源仓库 java-design-patterns 中 step-builder 模块的完整实现为依托,从模式目的、类图结构、源码级分步接口设计、测试用例到适用场景,为你还原一套可复制、可运行的完整实战方案。
什么是 Step Builder 模式
Step Builder 又被称为"分步构建"(Fluent Builder)。它是 Builder 模式的一个扩展,把复杂的对象构建过程拆解为一系列顺序固定、类型可感知的步骤:
- 编写创建步骤的内部类或接口,让每个方法都知道下一步可以展示什么(返回值类型即为下一步的接口);
- 在一个内部静态类中实现所有步骤接口;
- 最后一步是
BuildStep,负责真正创建所需对象。
从源码结构看,这种设计让 IDE 的自动补全成为"向导":使用者永远只能看到当前步骤允许的方法,编译期即可杜绝"漏配参数""顺序颠倒""调用不存在的 setter"等低级错误。
类图与整体结构
原文档中的类图(step-builder/etc/step-builder.png)直观展示了本模式在仓库中的结构:
Step Builder 类图
整个 com.iluwatar.stepbuilder 包由四类角色构成:
| 角色 | 类/接口 | 职责 |
|---|---|---|
| 目标产品 | Character |
拥有 name、fighterClass、wizardClass、weapon、spell、abilities 六个字段的复杂对象 |
| 构建器入口 | CharacterStepBuilder |
私有构造方法 + 静态入口 newBuilder(),返回第一步 NameStep |
| 步骤接口 | NameStep、ClassStep、WeaponStep、SpellStep、AbilityStep、BuildStep |
每个接口定义当前步骤可用的方法,方法返回值指向"下一步接口" |
| 步骤实现 | CharacterSteps(私有静态内部类) |
实现全部步骤接口,持有构建过程中的中间状态,最终在 build() 中组装 Character |
对应的 PlantUML 源码位于 step-builder/etc/step-builder.urm.puml,其中明确标注了 CharacterSteps 与六个步骤接口之间的实现关系(..|>),以及各接口与 CharacterStepBuilder 的嵌套组合关系(..+),可以作为后续绘制文档类图的参考模板。
此外,英文版文档还提供了时序图(step-builder/etc/step-builder-sequence-diagram.png),用于展示调用链:newBuilder() → name() → fighterClass()/wizardClass() → withWeapon()/withSpell() → withAbility()/noAbilities() → build()。
源码级剖析:六个步骤接口如何"指导"用户
第一步:NameStep
CharacterStepBuilder.java 中,NameStep 是整个链条的起点:
public interface NameStep {
ClassStep name(String name);
}
静态入口 newBuilder() 返回的是 NameStep,意味着用户调用 name() 是唯一合法操作,其余方法在编译期根本不可见。
第二步:ClassStep —— 分支选择
ClassStep 是链条中第一个"分叉点"(源码 L44-L52):
public interface ClassStep {
WeaponStep fighterClass(String fighterClass);
SpellStep wizardClass(String wizardClass);
}
选择 fighterClass(战士系)就走向武器步骤,选择 wizardClass(法师系)则走向法术步骤——后续可选项随分支自动收窄,这就是"没有混淆机会"的体现。
第三步:WeaponStep / SpellStep —— 可选分支
武器与法术两条分支结构对称(源码 L54-L72):
public interface WeaponStep {
AbilityStep withWeapon(String weapon);
BuildStep noWeapon();
}
public interface SpellStep {
AbilityStep withSpell(String spell);
BuildStep noSpell();
}
注意这里提供了显式的"跳过"方法(noWeapon() / noSpell()),用户要么提供装备、要么明确声明"不要",两者都返回 BuildStep,从而让"是否携带装备"成为不可遗漏的决策。
第四步:AbilityStep —— 循环步骤
能力是可变数量的集合字段,因此 AbilityStep 支持重复调用(源码 L74-L81):
public interface AbilityStep {
AbilityStep withAbility(String ability);
BuildStep noMoreAbilities();
BuildStep noAbilities();
}
withAbility(...)返回自身AbilityStep,可以连续追加多条能力;noMoreAbilities()表示"能力已添加完毕,进入收尾";noAbilities()表示"完全不要能力"。
最后一步:BuildStep —— 收尾校验
BuildStep 是整个链条的终点(源码 L83-L88):
public interface BuildStep {
Character build();
}
源码注释明确指出"Validation should be here",即对象校验逻辑应集中放在 build() 中,让非法状态在构造入口处被拦截。
步骤实现类 CharacterSteps 与 build() 的组装逻辑
CharacterSteps 是 CharacterStepBuilder 的私有静态内部类,同时实现全部六个步骤接口(源码 L91-L179)。它内部持有构建过程的临时状态:
private String name;
private String fighterClass;
private String wizardClass;
private String weapon;
private String spell;
private final List<String> abilities = new ArrayList<>();
每个步骤方法都遵循"赋值 + 返回 this 所代表的下一步接口"模式,例如:
@Override
public AbilityStep withWeapon(String weapon) {
this.weapon = weapon;
return this;
}
最终 build() 把临时状态组装成 Character(源码 L157-L178):
@Override
public Character build() {
var character = new Character(name);
if (fighterClass != null) {
character.setFighterClass(fighterClass);
} else {
character.setWizardClass(wizardClass);
}
if (weapon != null) {
character.setWeapon(weapon);
} else {
character.setSpell(spell);
}
if (!abilities.isEmpty()) {
character.setAbilities(abilities);
}
return character;
}
组装规则可以概括为三点:
- 职业二选一:
fighterClass与wizardClass互斥,以"非空优先"决定最终写入哪个字段; - 装备二选一:
weapon与spell互斥,同样按非空判断写入; - 能力可选:只有
abilities非空时才写入集合字段,否则保持null(对应noAbilities()场景)。
而目标产品 Character.java 是一个字段丰富的简单 POJO,使用 Lombok 的 @Getter / @Setter 生成访问器,构造器仅接收 name(必填项),其余字段全部通过构建器按步骤填充。其 toString() 方法会根据字段空值动态拼接描述,方便日志输出验证。
程序化示例:三种角色的构建过程
仓库入口 App.java 演示了三种典型构建路径:
public static void main(String[] args) {
var warrior =
CharacterStepBuilder.newBuilder()
.name("Amberjill")
.fighterClass("Paladin")
.withWeapon("Sword")
.noAbilities()
.build();
LOGGER.info(warrior.toString());
var mage =
CharacterStepBuilder.newBuilder()
.name("Riobard")
.wizardClass("Sorcerer")
.withSpell("Fireball")
.withAbility("Fire Aura")
.withAbility("Teleport")
.noMoreAbilities()
.build();
LOGGER.info(mage.toString());
var thief =
CharacterStepBuilder.newBuilder().name("Desmond").fighterClass("Rogue").noWeapon().build();
LOGGER.info(thief.toString());
}
三段构建分别覆盖了三条完整路径:
- 战士:
name → fighterClass → withWeapon → noAbilities → build,能力字段为空; - 法师:
name → wizardClass → withSpell → withAbility(×2) → noMoreAbilities → build,走"跳过法术/跳过能力"分支; - 盗贼:
name → fighterClass → noWeapon → build,走"明确不要武器"分支。
运行后控制台输出(依赖 slf4j + logback,见 step-builder/pom.xml 中的依赖声明):
INFO com.iluwatar.stepbuilder.App -- This is a Paladin named Amberjill armed with a Sword.
INFO com.iluwatar.stepbuilder.App -- This is a Sorcerer named Riobard armed with a Fireball and wielding [Fire Aura, Teleport] abilities.
INFO com.iluwatar.stepbuilder.App -- This is a Rogue named Desmond armed with a with nothing.
想在本机复现,可在仓库根目录执行 ./mvnw 相关命令针对 step-builder 模块编译运行,入口主类为 com.iluwatar.stepbuilder.App(已通过 maven-assembly-plugin 在 pom.xml 中配置为 manifest 主类)。
测试用例:验证不同分支的组合正确性
CharacterStepBuilderTest.java 用 6 个测试用例覆盖了构建器的全部组合路径,可以直接作为行为规格说明:
| 测试方法 | 构建路径 | 验证点 |
|---|---|---|
testBuildWizard |
法师 + 法术 + 2 项能力 + noMoreAbilities |
职业、法术字段正确,能力列表恰好 2 项且包含指定值 |
testBuildPoorWizard |
法师 + noSpell(不选法术) |
spell 与 abilities 均为 null |
testBuildWeakWizard |
法师 + 法术 + noAbilities |
spell 有值而 abilities 为 null |
testBuildWarrior |
战士 + 武器 + 2 项能力 + noMoreAbilities |
职业、武器字段正确,能力列表 2 项 |
testBuildPoorWarrior |
战士 + noWeapon |
weapon 与 abilities 均为 null |
testBuildWeakWarrior |
战士 + 武器 + noAbilities |
weapon 有值而 abilities 为 null |
这些断言恰好印证了 build() 中的组装规则:noSpell/noWeapon/noAbilities 三种"跳过"分支都会留下 null 字段,而"追加"分支则正确累积到集合中。此外 AppTest.java 验证了 App.main 可无异常执行,保证示例代码可运行。
何时使用 Step Builder 模式
根据原文档与源码注释(App.java 中的 Intent / Applicability 说明),当以下条件同时成立时适合采用 Step Builder:
- 创建复杂对象的算法需要独立于对象组成部分及其组装方式——
Character的六个字段如何组合由build()统一负责,调用方无须关心; - 构造过程必须允许对象有不同的表示形式——战士、法师、盗贼三条路径产出完全不同的
Character; - 构造过程中顺序很重要——
name必须先于职业,职业决定装备分支,装备之后才允许声明能力,顺序由返回值类型在编译期强制保证。
典型应用场景包括:复杂配置对象的组装、多字段数据库记录对象的构建、UI 元素的分步配置等。对于"字段数量多且彼此存在依赖关系"的领域对象,Step Builder 能显著提升调用方的代码可读性与可维护性。
优点与权衡
优点
- 提升代码可读性与可维护性:构建过程被拆成语义明确的步骤链,调用方代码即文档;
- 增强构建灵活性:
ClassStep的分支与"跳过"方法让同一种对象可以有不同的构建路径; - 通过分离"构造过程"与"对象表示"鼓励不可变性设计——所有字段通过构建器一次性写入。
权衡
- 需要额外引入多个步骤接口与实现类,代码结构比普通 Builder 更复杂;
- 步骤较多时链式调用代码可能显得冗长;
- 步骤接口一旦确定,增删步骤会影响所有调用方(可通过合理划分步骤粒度缓解)。
从 step-builder/README.md 的说明看,Step Builder 与本仓库中的 builder 模式同属创建型模式家族:Builder 强调"一个构建器多个构建方法",而 Step Builder 强调"每一步只暴露下一步接口";两者常与 Fluent Interface 搭配使用,也可以在构造复杂对象时与 Factory Method 协同封装构建器自身的创建逻辑。
结语
通过 java-design-patterns 仓库中 step-builder 模块的完整源码(CharacterStepBuilder.java、Character.java、App.java)与六组测试用例,可以看到 Step Builder 的真正价值:用类型系统把"如何正确构造"变成编译期约束,用返回值接口把"下一步能做什么"变成 IDE 提示。当你的领域对象字段众多、字段之间存在依赖与顺序关系时,这套模式是比传统 Builder 更严谨、对调用方更友好的进阶方案。