1. 从一个真实的编译报错说起

如果你写过 Java，大概率用过 Lombok 的@Builder。它确实省事，一个注解下去，链式调用就来了，代码清爽不少。但很多人第一次在继承场景里用它，都会撞上同一堵墙——子类加@Builder，编译直接报错，提示父类没有无参构造器，或者提示 builder 方法返回类型对不上。

这个问题的本质，是@Builder默认只认自己所在的那个类，它不会自动帮你把父类的字段也纳入构建流程。换句话说，Lombok 生成的 builder 是一个"只顾自己"的 builder。父类字段怎么办？它不管。这就导致子类一旦继承，构建出来的对象要么父类字段全是默认值，要么干脆编译不过。

我见过不少团队在这个点上反复踩坑：有人干脆放弃继承，把字段全塞一个类里；有人手写 builder，写到手酸；还有人用@SuperBuilder但没搞清它和@Builder的区别，结果序列化时又出问题。这些坑其实都有清晰的解法，只是散落在各种文档和 issue 里，没人系统整理过。

这篇内容就是把这几种方案掰开揉碎讲清楚。不管你是刚接触 Lombok 的新手，还是已经用过几年但一直没深究继承场景的老手，看完都能找到适合自己项目的做法。我会从报错原因讲起，把@Builder、@SuperBuilder、手写 builder 三条路各自的适用边界、实操步骤和隐藏陷阱都过一遍，最后给出一套可以直接抄的选型判断标准。

2. 为什么子类加 @Builder 会编译失败

2.1 Lombok 生成 builder 的底层逻辑

要理解报错，得先知道@Builder到底生成了什么。当你在一个类上标注@Builder，Lombok 在编译期会往这个类里注入一个静态内部类，名字叫XxxBuilder，同时给原类加一个私有的全参构造器，再提供一个静态的builder()方法返回这个 builder 实例。

关键点在于：这个全参构造器只包含当前类自己声明的字段。它不会去管父类的字段，因为 Lombok 在编译期处理注解时，是以单个类为单位的，它看不到也不关心继承链上其他类的结构。

这就埋下了第一个雷。假设父类Parent有一个字段name，子类Child有一个字段age。你在Child上加@Builder，Lombok 生成的全参构造器签名是Child(int age)，而不是Child(String name, int age)。父类的name根本没被纳入。

2.2 编译报错的两种典型形态

实际编译时，报错通常表现为两种。第一种是"constructor Parent in class Parent cannot be applied to given types"，意思是子类的构造器里隐式调用了super()，但父类没有无参构造器。为什么会这样？因为一旦你给父类加了@Builder或者@AllArgsConstructor，父类的默认无参构造器就消失了，而子类构造器第一行默认要调super()，找不到就报错。

第二种是"method does not override or implement"，或者 builder 的build()方法返回类型和预期不符。这种情况多出现在你试图手动扩展 builder 的时候，方法签名对不上。

我整理了一个对照表，把常见报错和根因列出来，方便你快速定位：

2.3 一个最小复现案例

光说理论不够直观，我写一个最小复现的例子。父类这样写：

@Builder public class Parent { private String name; }

子类这样写：

@Builder public class Child extends Parent { private int age; }

编译直接挂掉。原因就是Parent因为@Builder生成了全参构造器Parent(String name)，默认无参构造器没了。而Child的构造器里隐式super()找不到匹配，报错。

如果你把父类的@Builder去掉，只留子类的，编译能过，但构建出来的Child对象里name永远是null，因为子类 builder 压根没管父类字段。这就是最坑的地方——不报错，但结果是错的，排查起来更费劲。

提示：遇到"不报错但字段为 null"的情况，优先检查是不是继承链上某个类的字段没被 builder 覆盖。这类问题在单元测试里如果没断言父类字段，很容易漏过去。

3. @SuperBuilder 的适用边界与实操细节

3.1 @SuperBuilder 和 @Builder 的本质差异

@SuperBuilder是 Lombok 后来专门为继承场景推出的注解。它和@Builder最大的区别在于：@SuperBuilder会沿着继承链往上走，把父类的字段也纳入 builder 的构建范围。它生成的 builder 是一个带继承关系的 builder，子类 builder 继承自父类 builder。

这个设计带来的直接好处是，你在子类 builder 上可以链式调用父类字段的 setter。比如Child.builder().name("x").age(1).build()，name来自父类，age来自子类，一次构建全部搞定。

但要注意，@SuperBuilder要求继承链上的每一个类都标注它，不能父类用@Builder、子类用@SuperBuilder，那样会出问题。这是很多人第一次用时报错的原因。

3.2 正确使用的完整代码模板

下面是我在实际项目里验证过的标准写法。父类：

@SuperBuilder @Getter @Setter public class Parent { private String name; private int type; }

子类：

@SuperBuilder @Getter @Setter public class Child extends Parent { private int age; private String tag; }

构建时：

Child child = Child.builder() .name("test") .type(1) .age(18) .tag("demo") .build();

这样name和type都能正确赋值。注意@SuperBuilder生成的 builder 类名和@Builder不同，它是Child.ChildBuilder这种带泛型参数的内部类，所以如果你有反射或者序列化代码依赖 builder 类名，需要同步调整。

3.3 版本兼容与常见配置陷阱

@SuperBuilder是 Lombok 1.18.2 才引入的，早期版本没有。如果你项目里 Lombok 版本低于这个，要么升级，要么只能走手写路线。升级时注意 IDE 插件也要同步更新，否则 IDE 里可能标红但命令行编译能过，这种"假报错"很影响开发体验。

另一个坑是@SuperBuilder和@NoArgsConstructor的冲突。因为@SuperBuilder会生成一个全参构造器，如果你同时需要无参构造器（比如给 Jackson 反序列化用），得显式加上@NoArgsConstructor，并且确保父类也有无参构造器。否则反序列化时会报"no suitable constructor"。

我踩过一次这个坑：接口返回的对象用@SuperBuilder构建，但接收请求体时用 Jackson 反序列化，结果因为缺无参构造器一直报错。后来在父子类上都补了@NoArgsConstructor和@AllArgsConstructor才解决。这个组合配置我建议直接记下来：

@SuperBuilder @NoArgsConstructor @AllArgsConstructor @Getter @Setter public class Child extends Parent { ... }

父类同样要加这三个注解，缺一不可。

4. 手写 Builder 的完整实现路径

4.1 什么情况下必须放弃注解

@SuperBuilder虽然好用，但有些场景它搞不定。比如你需要 builder 里做字段校验、需要 builder 支持部分字段可选、或者你的继承层级超过三层且每层字段都很多，@SuperBuilder生成的代码会变得很臃肿，调试困难。

还有一种情况是团队规范限制，不允许在实体类上堆太多 Lombok 注解，怕影响可读性。这时候手写 builder 反而是更可控的选择。

手写 builder 的核心思路是：在子类 builder 里持有一个父类 builder 的引用，或者直接持有所有字段，构建时先构建父类部分再构建子类部分。听起来复杂，其实有固定套路。

4.2 子类 builder 持有父类 builder 的写法

这是最推荐的手写方式，结构清晰，扩展性好。父类 builder：

public class Parent { private final String name; private final int type; protected Parent(ParentBuilder<?, ?> builder) { this.name = builder.name; this.type = builder.type; } public static abstract class ParentBuilder<C extends Parent, B extends ParentBuilder<C, B>> { private String name; private int type; public B name(String name) { this.name = name; return self(); } public B type(int type) { this.type = type; return self(); } protected abstract B self(); public abstract C build(); } }

子类 builder 继承父类 builder：

public class Child extends Parent { private final int age; protected Child(ChildBuilder<?, ?> builder) { super(builder); this.age = builder.age; } public static ChildBuilder<?, ?> builder() { return new ChildBuilderImpl(); } public static abstract class ChildBuilder<C extends Child, B extends ChildBuilder<C, B>> extends ParentBuilder<C, B> { private int age; public B age(int age) { this.age = age; return self(); } } private static final class ChildBuilderImpl extends ChildBuilder<Child, ChildBuilderImpl> { @Override protected ChildBuilderImpl self() { return this; } @Override public Child build() { return new Child(this); } } }

这套写法的精髓在于泛型自引用B extends ParentBuilder<C, B>，它保证了链式调用时返回的是子类 builder 类型，而不是父类。这样你才能连续调用.name().age()而不需要强转。

4.3 构建顺序与字段校验的插入点

手写 builder 的一个额外好处是可以在build()方法里插入校验逻辑。比如age必须大于 0，name不能为空。这些校验放在build()里最合适，因为此时所有字段都已经设置完毕。

@Override public Child build() { if (age <= 0) { throw new IllegalArgumentException("age must be positive"); } if (name == null || name.isEmpty()) { throw new IllegalArgumentException("name required"); } return new Child(this); }

注意校验顺序要和字段依赖关系一致。如果某个字段的校验依赖另一个字段的值，要先校验被依赖的。这个细节在字段多的时候容易乱，建议按字段声明顺序写校验。

提示：手写 builder 时，父类构造器建议用protected而不是public，防止外部绕过 builder 直接 new 对象，破坏构建约束。

5. 三种方案横向对比与选型判断

5.1 功能维度对比

我把三种方案在关键维度上做了对比，方便你一眼看出差异：

从表里能看出，@SuperBuilder在大多数继承场景下是性价比最高的选择。手写 builder 只在需要校验或特殊控制时才值得。

5.2 性能与编译期开销

有人担心@SuperBuilder生成的代码多，会不会影响运行性能。实测下来，builder 模式本身的性能开销主要在对象创建次数上，@SuperBuilder和手写 builder 在运行时几乎没有差异，因为生成的字节码逻辑是一样的。差异主要在编译期，@SuperBuilder会让编译稍微慢一点，但项目规模不大时感知不到。

真正需要注意的是@SuperBuilder生成的 builder 类会带泛型参数，如果你的项目用了混淆或代码缩减工具，要确保这些泛型信息不被误删，否则运行时会报类型转换错误。

5.3 我的选型决策树

基于实际项目经验，我总结了一个简单的判断流程：

1. 如果继承链只有一层，且不需要字段校验，直接用@SuperBuilder，父子类都加。
2. 如果继承链超过两层，先评估字段总数。字段少（每层少于 5 个）继续用@SuperBuilder；字段多且需要校验，转手写。
3. 如果项目需要 Jackson 反序列化，无论用哪种方案，父子类都要补@NoArgsConstructor。
4. 如果团队禁止 Lombok，直接手写，按第 4 节的模板来。

这个决策树帮我省了很多纠结时间。你可以根据自己的项目情况微调，但核心逻辑是：优先用注解，注解搞不定再手写，不要一上来就手写。

6. 那些文档里不会写的踩坑记录

6.1 序列化框架的兼容问题

用@SuperBuilder时，如果对象要经过 JSON 序列化和反序列化，builder 本身不参与这个过程，但构造器的存在与否会影响反序列化。Jackson 默认需要无参构造器，或者用@JsonCreator标注一个构造器。@SuperBuilder生成的全参构造器没有@JsonCreator，所以 Jackson 认不出来。

解决办法有两个：一是加@NoArgsConstructor让 Jackson 用字段反射赋值；二是给全参构造器加@JsonCreator和@JsonProperty。我一般选第一种，简单省事。但要注意，加了@NoArgsConstructor后，字段就不能是final了，否则无参构造器没法初始化。这是一个取舍：要不可变对象，就要手写@JsonCreator；要省事，就放弃final。

6.2 IDE 与编译器的行为差异

IntelliJ IDEA 对 Lombok 的支持依赖插件版本。我遇到过好几次 IDE 里@SuperBuilder标红，但mvn compile完全正常。这种情况通常是插件版本落后于 Lombok 依赖版本。解决办法是升级插件，或者在 IDE 设置里开启 annotation processing。

另一个差异是 Eclipse 和 javac 对泛型推断的处理略有不同。同样的@SuperBuilder代码，在 Eclipse 里可能报"类型推断失败"，在 javac 里正常。如果团队混用 IDE，建议统一用 Maven 或 Gradle 命令行编译作为准绳，IDE 报错先别慌，跑一遍命令行确认。

6.3 继承链上的注解遗漏

最常见的低级错误是：父类加了@SuperBuilder，子类忘了加，或者反过来。这种情况下编译可能不报错，但构建出来的对象父类字段全是默认值。因为子类如果只用@Builder，它生成的 builder 不包含父类字段，而父类的@SuperBuilder生成的 builder 又没被调用。

排查这类问题有个技巧：在build()之后打印所有字段，或者写单元测试断言每个字段。我习惯在基类里写一个toString()，构建完直接打印，一眼就能看出哪个字段没赋值。

提示：如果继承链上有抽象类，抽象类也要加@SuperBuilder，否则子类 builder 无法正确继承。抽象类加@SuperBuilder后，它自己不能直接build()，但可以作为 builder 链的一环。

7. 一套可以直接抄的落地配置

7.1 父子类注解组合模板

经过多个项目验证，下面这套注解组合是最稳的，兼顾了 builder、序列化和不可变性：

父类：

@SuperBuilder @Getter @Setter @NoArgsConstructor @AllArgsConstructor public class BaseEntity { private String id; private Long createTime; }

子类：

@SuperBuilder @Getter @Setter @NoArgsConstructor @AllArgsConstructor @EqualsAndHashCode(callSuper = true) public class UserEntity extends BaseEntity { private String username; private String email; }

注意@EqualsAndHashCode(callSuper = true)必须加，否则 equals 比较时会忽略父类字段，导致两个父类字段不同但子类字段相同的对象被判为相等。这个坑在集合去重时特别致命。

7.2 单元测试的断言要点

写完 builder 代码，一定要补单元测试。测试重点不是 builder 能不能用，而是父类字段有没有被正确赋值。我通常写三个断言：父类字段非空、子类字段非空、默认值符合预期。

@Test public void testBuilderWithInheritance() { UserEntity user = UserEntity.builder() .id("1001") .createTime(System.currentTimeMillis()) .username("tester") .email("test@example.com") .build(); assertNotNull(user.getId()); assertNotNull(user.getCreateTime()); assertEquals("tester", user.getUsername()); assertEquals("test@example.com", user.getEmail()); }

如果父类字段断言失败，说明 builder 继承链断了，回去检查注解是否遗漏。

7.3 版本锁定与升级建议

Lombok 版本建议锁定在 1.18.20 以上，这个版本对@SuperBuilder的泛型处理更稳定。升级时先在测试分支跑全量编译和单元测试，确认没有泛型推断相关的报错再合并。如果项目用了 Spring Boot，注意 Spring Boot 的依赖管理里可能指定了 Lombok 版本，要显式覆盖成你需要的版本。

我在实际项目里还遇到过一个情况：多个模块依赖不同版本的 Lombok，导致编译时行为不一致。解决办法是在父 pom 里用dependencyManagement统一版本，所有子模块继承。这个配置一次做好，后面省很多事。

8. 关于继承与构建的一点个人体会

用了这么多年 Lombok，我越来越觉得@Builder和继承的冲突，本质上是"组合优于继承"这个原则的一个缩影。很多时候我们为了复用几个字段去搞继承，结果引入了一堆 builder、序列化、equals 的麻烦。如果字段复用不多，把公共字段抽成一个独立的类，用组合的方式持有，反而更清爽。

当然，继承不是不能用，只是用的时候要把 builder 这条链路想清楚。我的习惯是：新建一个继承结构时，先把父子类的注解组合定下来，写一个最小的构建测试跑通，再往里加业务字段。这样能把问题扼杀在早期，不至于字段堆到几十个才发现 builder 不对。

最后分享一个小技巧：如果你不确定某个字段到底有没有被 builder 覆盖，在build()方法里加一行日志，打印所有字段值。跑一次测试，哪些是 null 一目了然。这个方法比看文档快得多，尤其适合排查那些"不报错但结果不对"的隐蔽问题。