Lombok @SuperBuilder 解谜之旅 ：轻松搞定继承下的建造者模式！

Lombok @SuperBuilder 解谜之旅 ‍♂️：轻松搞定继承下的建造者模式！

嘿，各位代码工匠们！ 在我们的Java开发日常中，Lombok无疑是一位超级给力的助手，它通过各种神奇的注解，极大地简化了我们的样板代码。其中，@Builder 注解是我们构建对象时的老朋友了。但是，当继承（Inheritance）这个“小妖精”出现时，标准的 @Builder 似乎就有点力不从心了。这时候，就轮到它的“超级”形态——@SuperBuilder 登场啦！

今天，我们就来深入探讨一下 @SuperBuilder，看看它到底解决了什么问题，以及如何在我们的项目中优雅地使用它。

先来个快速总结

特性	描述
核心功能	解决继承体系中 @Builder 注解的局限性，实现父子类 Builder 的正确继承。
何时使用	当你的类存在继承关系，并且希望为整个继承链上的类都提供流畅的建造者模式时。
⚠️ 注意事项	父类和子类都必须使用 @SuperBuilder。父类通常需要 @NoArgsConstructor (无参构造函数) 或 @AllArgsConstructor (全参构造函数) 来配合。
✨ 优点	代码简洁、类型安全、支持链式调用、完美支持继承。
局限性	相比 @Builder，对父类的注解有额外要求。

为什么标准的 @Builder 在继承时会“翻车”？

想象一下这个场景：

// 父类
@Getter
@Builder // 标准 Builder
@AllArgsConstructor // 假设有个全参构造
class Vehicle {
    private String brand;
    private int wheels;
}

// 子类
@Getter
@EqualsAndHashCode(callSuper = true) // 确保 equals 和 hashCode 正确处理父类字段
@ToString(callSuper = true) // 确保 toString 正确处理父类字段
@Builder // 标准 Builder
class Car extends Vehicle {
    private int doors;
    private String color;

    // 如果使用 @Builder，Lombok 会尝试生成类似这样的构造函数
    // Car(String brand, int wheels, int doors, String color) { ... }
    // 但它无法直接调用 super(brand, wheels) 并设置自己的字段，
    // 因为 @Builder 生成的 builder 不知道如何处理父类字段的传递。
}

如果你尝试使用 Car.builder()，你会发现 CarBuilder 只能设置 doors 和 color，而无法设置从 Vehicle 继承来的 brand 和 wheels。这是因为 CarBuilder 并不会自动继承或包含 VehicleBuilder 的功能。这就是 @Builder 在继承面前的窘境。

‍♂️ @SuperBuilder 闪亮登场！

@SuperBuilder 就是为了解决这个问题而生的！它允许子类的 Builder 继承父类的 Builder，从而能够设置继承链上所有类的字段。

让我们用 @SuperBuilder 改造上面的例子：

// 父类
import lombok.Getter;
import lombok.NoArgsConstructor; // 通常需要一个无参构造
import lombok.experimental.SuperBuilder;

@Getter
@SuperBuilder // ✨ 注意这里！
@NoArgsConstructor // 父类通常需要一个无参构造函数，或者一个受保护的构造函数供子类builder使用
// 或者 @AllArgsConstructor，但 @NoArgsConstructor 更常见于基类
class Vehicle {
    private String brand;
    private int wheels;
}

// 子类
import lombok.EqualsAndHashCode;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.ToString;
import lombok.experimental.SuperBuilder;

@Getter
@EqualsAndHashCode(callSuper = true)
@ToString(callSuper = true)
@SuperBuilder // ✨ 注意这里！
@NoArgsConstructor // 子类也通常需要
class Car extends Vehicle {
    private int doors;
    private String color;
}

// 使用
public class Main {
    public static void main(String[] args) {
        Car myCar = Car.builder()
                .brand("Tesla")     // ✔️ 可以设置父类字段
                .wheels(4)          // ✔️ 可以设置父类字段
                .doors(4)           // ✔️ 可以设置子类字段
                .color("Red")       // ✔️ 可以设置子类字段
                .build();

        System.out.println(myCar); // 输出: Car(super=Vehicle(brand=Tesla, wheels=4), doors=4, color=Red)
    }
}

看！现在 Car.builder() 返回的 CarBuilder 实例，不仅可以设置 Car 自己的字段，还能流畅地设置父类 Vehicle 的字段。完美！

⚙️ @SuperBuilder 是如何工作的？(Mermaid 流程图)

Lombok 在背后为我们做了很多巧妙的工作。简单来说：

1. 当你在父类上使用 @SuperBuilder，Lombok 会为父类生成一个抽象的 Builder 类（例如 VehicleBuilder），这个 Builder 类包含了设置父类字段的方法。
2. 当你在子类上使用 @SuperBuilder，Lombok 会为子类生成一个具体的 Builder 类（例如 CarBuilder），这个 CarBuilder 会继承自父类的 VehicleBuilder。
3. 这样，CarBuilder 就同时拥有了设置父类字段和子类字段的能力。

开发者在父类 ParentClass 添加 @SuperBuilder

Lombok 生成 ParentClassBuilder (通常是抽象的)

ParentClassBuilder 包含设置 ParentClass 字段的方法 (返回自身类型以支持链式调用)

开发者在子类 ChildClass 添加 @SuperBuilder

Lombok 生成 ChildClassBuilder

ChildClassBuilder 继承 ParentClassBuilder

ChildClassBuilder 包含设置 ChildClass 字段的方法 (返回自身类型)

ChildClassBuilder 也拥有设置 ParentClass 字段的方法 (通过继承得来)

调用 ChildClass.builder().parentField(...).childField(...).build()

最终通过一系列内部调用，创建 ChildClass 实例并填充所有字段

实际开发中的应用场景与社区反馈

@SuperBuilder 在很多场景下都非常有用：

1. 实体类 (Entities) 继承：在 JPA (Jakarta Persistence API, Java 持久化 API) 等 ORM (Object-Relational Mapping, 对象关系映射) 框架中，我们经常会有一个 BaseEntity (包含 id, createdDate 等公共字段)，然后具体的业务实体类继承它。这时使用 @SuperBuilder 就能方便地构建这些实体对象。
   • 社区反馈 (Stack Overflow, GitHub Issues)：很多开发者在遇到 @Builder 无法处理继承时，@SuperBuilder 成为了他们的救星。最常见的问题就是忘记在父类也加上 @SuperBuilder，或者父类缺少合适的构造函数（通常是无参构造）。
2. DTO (Data Transfer Object, 数据传输对象) 继承：当 API (Application Programming Interface, 应用程序编程接口) 的请求或响应体存在层级结构，且有共享字段时，@SuperBuilder 同样适用。
3. 任何需要构建复杂继承树对象的场景。

来自社区的经验之谈 ️：

• 父类也必须加 @SuperBuilder！ 这是最容易犯的错误。如果父类没有 @SuperBuilder，子类的 @SuperBuilder 就会在编译时报错，提示找不到父类的 Builder (例如 BaseEntityBuilder not found)。
• 构造函数很重要！ 父类通常需要一个 protected 或 public 的无参构造函数 (@NoArgsConstructor)，或者一个包含所有字段的构造函数 (@AllArgsConstructor)，Lombok 的 @SuperBuilder 实现会依赖它们。子类也类似。
• @SuperBuilder(toBuilder = true)：和 @Builder 一样，@SuperBuilder 也支持 toBuilder = true 参数，这允许你从一个已存在的对象实例创建一个新的 Builder，方便修改部分属性后构建新对象。
• 善用 Delombok：如果你想深入理解 @SuperBuilder 到底生成了什么代码，可以在你的 IDE (Integrated Development Environment, 集成开发环境) 中使用 Lombok 插件的 “Delombok” 功能，或者通过构建工具执行 Delombok 任务。这能帮你揭开 Lombok 的神秘面纱。

@SuperBuilder 构建过程时序图 (Sequence Diagram)

让我们通过一个简化的时序图来看看调用 Child.builder().parentField(...).childField(...).build() 时大致发生了什么：

客户端代码 ChildClass.ChildBuilder ParentClass.ParentBuilder (作为ChildBuilder的超类部分) ChildClass 实例 builder() 创建 ChildBuilder 实例 parentField("父类属性值") ChildBuilder 调用 继承自 ParentBuilder 的 parentField 方法 (super) parentField("父类属性值") 存储父类属性值 返回 ChildBuilder (this) childField("子类属性值") ChildBuilder 存储 自己的属性值 返回 ChildBuilder (this) build() 调用内部的 build 方法 开始构建实例 new ChildClass() (或通过特定构造函数) 创建实例 设置所有父类和子类字段 返回构建好的实例 返回 ChildClass 实例 客户端代码 ChildClass.ChildBuilder ParentClass.ParentBuilder (作为ChildBuilder的超类部分) ChildClass 实例

这个时序图简化了实际的调用链，但核心思想是：子类的 Builder 负责协调，调用父类 Builder 的逻辑来设置父类字段，然后设置自己的字段，最后构建出完整的对象。

英文缩写全称及中文

• DTO: Data Transfer Object (数据传输对象)
• JPA: Jakarta Persistence API (Java 持久化 API) - 以前也常被称为 Java Persistence API
• ORM: Object-Relational Mapping (对象关系映射)
• API: Application Programming Interface (应用程序编程接口)
• IDE: Integrated Development Environment (集成开发环境)

总结

@SuperBuilder 是 Lombok 提供的一个强大工具，它优雅地解决了标准 @Builder 在类继承场景下的不足。通过确保父类和子类都使用 @SuperBuilder，并配合适当的构造函数，我们可以轻松地为整个继承体系构建出类型安全、流式调用的建造者。

下次当你的对象模型涉及到继承，并且需要 Builder 模式时，别忘了 @SuperBuilder 这位超级英雄！它会让你的代码更简洁，开发更高效！

希望这篇博客对你有所帮助！如果你有任何问题或经验分享，欢迎在评论区留言！

---

思维导图 (Markdown 格式)