Step Builder(分步构建)模式在 Java 中的落地实践:以 java-design-patterns 仓库源码为例

原创2026-10-02 22:54:301,881 阅读
文章标签:示例工程教程

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;
}

组装规则可以概括为三点:

  1. 职业二选一:fighterClass 与 wizardClass 互斥,以"非空优先"决定最终写入哪个字段;
  2. 装备二选一:weapon 与 spell 互斥,同样按非空判断写入;
  3. 能力可选:只有 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 更严谨、对调用方更友好的进阶方案。

登录后查看全文
java-design-patterns