解决SpringBoot中Lombok的@Data注解编译错误-代码聚汇网

解决SpringBoot中Lombok的@Data注解编译错误

鲸吃瓜·2026-08-07·阅读 22 GEO检测（免费）

SpringBootLombok注解处理器

|难度：普通|阅读约 13 分钟

1. 问题现象与初步诊断

当你在SpringBoot项目中遇到"Lombok annotation handler class lombok.javac.handlers.HandleData failed on Dxx.java"这个错误时，通常会在编译阶段突然中断。控制台会显示完整的堆栈跟踪，最顶部就是这条错误信息，后面往往跟着java.lang.StackOverflowError。

这个错误的核心特征是：

发生在使用@Data注解的Java类文件上（示例中的Dxx.java）
与Lombok的注解处理器lombok.javac.handlers.HandleData直接相关
伴随堆栈溢出错误，表明存在某种递归调用问题

我第一次遇到这个问题时，发现它有个奇怪的特性：同样的代码在同事机器上能正常编译，但在我的开发环境就会报错。这提示我们环境配置差异可能是关键因素。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 错误根源深度解析

2.1 Lombok工作原理剖析

要理解这个错误，需要先了解Lombok的工作机制。Lombok通过Java的注解处理器（Annotation Processor）在编译时修改抽象语法树（AST）。具体到@Data注解：

编译器（javac）开始处理源代码时，会识别出@Data注解
调用对应的HandleData处理器
HandleData会为类生成getter/setter/equals/hashCode/toString等方法
修改后的AST继续后续编译流程

2.2 为什么会出现StackOverflowError

当出现StackOverflowError时，说明HandleData处理器陷入了无限递归。经过多次实践验证，这通常由以下情况触发：

循环引用：类A包含类B实例，类B又包含类A实例，且都使用了@Data
自引用：类内部有指向自身的字段（例如树形结构的parent/children）
Lombok版本与JDK/IDE不兼容：特别是使用较新JDK时

重要提示：在Java 16+版本中，由于JEP 396默认强封装JDK内部API，可能导致Lombok无法正常工作，这也是常见诱因之一。

3. 解决方案与实操步骤

3.1 紧急解决方案（快速修复）

如果急需让项目先跑起来，可以尝试这些方法：

临时移除@Data：

java复制// 替换为显式注解
@Getter
@Setter
@ToString(exclude = "循环引用字段")
@EqualsAndHashCode(exclude = "循环引用字段")

使用@Builder替代：

java复制@Builder
@NoArgsConstructor
@AllArgsConstructor
public class Dxx {
    // 字段定义
}

3.2 彻底解决方案

3.2.1 处理循环引用问题

对于存在双向引用的类，应该：

在toString()和equals()中排除反向引用：

java复制@Data
public class A {
    @ToString.Exclude
    @EqualsAndHashCode.Exclude
    private B b;
}

或者使用手动实现的equals()/toString()替代@Data

3.2.2 环境配置检查清单

按照以下步骤排查环境问题：

验证Lombok版本：

bash复制# 查看依赖树中的Lombok版本
mvn dependency:tree | grep lombok

检查IDE集成：
- IntelliJ IDEA：确保启用注解处理器
  - Settings → Build → Compiler → Annotation Processors
  - 勾选"Enable annotation processing"
- Eclipse：安装最新Lombok插件

JDK兼容性调整：
对于Java 16+，在启动配置添加：

bash复制--add-opens=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED

3.3 构建工具配置示例

Maven配置样例：

xml复制<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <source>17</source>
                <target>17</target>
                <compilerArgs>
                    <arg>-J--add-opens=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED</arg>
                </compilerArgs>
            </configuration>
        </plugin>
    </plugins>
</build>

Gradle配置样例：

groovy复制tasks.withType(JavaCompile) {
    options.compilerArgs += ["--add-opens", "jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED"]
}

4. 深度避坑指南

4.1 容易忽略的配置细节

多模块项目的陷阱：
- 父pom中定义的Lombok版本可能被子模块覆盖
- 解决方案：在dependencyManagement中锁定版本
IDE缓存问题：
- 有时需要手动清理：
  - IntelliJ：File → Invalidate Caches
  - Eclipse：Project → Clean
构建工具插件冲突：
- 比如maven-compiler-plugin版本过旧
- 推荐使用3.8.0+版本

4.2 特殊场景处理

4.2.1 使用记录类（Java 14+）

如果使用Java 14+的记录类（record），可以完全避免Lombok：

java复制public record User(String name, int age) {}

4.2.2 与MapStruct配合使用

当同时使用Lombok和MapStruct时，编译顺序很重要：

确保Lombok先于MapStruct执行
在maven-compiler-plugin中明确指定：

xml复制<annotationProcessorPaths>
    <path>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>${lombok.version}</version>
    </path>
    <path>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct-processor</artifactId>
        <version>${mapstruct.version}</version>
    </path>
</annotationProcessorPaths>

5. 版本兼容性矩阵

根据实际项目经验整理的兼容性参考：

Lombok版本	推荐JDK版本	支持Spring Boot版本	注意事项
1.18.16	8-15	2.3.x-2.7.x	最稳定版本
1.18.24	11-17	2.7.x-3.0.x	需要--add-opens
1.18.28+	17+	3.0.x+	推荐用于新项目

6. 替代方案评估

如果问题持续无法解决，可以考虑这些替代方案：

手动实现方法：
- 优点：完全可控
- 缺点：增加样板代码
使用记录类（Java 14+）：
- 优点：语言原生支持
- 缺点：功能不如Lombok全面
其他代码生成工具：
- Immutables
- AutoValue

在最近的一个微服务项目中，我们遇到这个问题后最终采用的方案是：对核心领域模型使用显式@Getter/@Setter，对DTO保持使用@Data。这样既避免了递归问题，又保持了代码简洁性。

7. 排查流程图解

当遇到这个问题时，建议按照以下流程排查：

检查类结构 → 是否存在循环引用？
- 是：使用@Exclude或重构模型
- 否：进入下一步
检查环境：
- Lombok版本是否≥1.18.24？
- JDK版本是否匹配？
- IDE插件是否安装？
尝试最小化复现：
- 新建测试类单独编译
- 逐步添加注解/依赖
检查构建配置：
- 是否配置了--add-opens？
- 编译插件版本是否兼容？

8. 实战案例分享

去年在电商平台项目中，我们遇到一个典型场景：

java复制@Data
public class Order {
    private User user;
    private List<OrderItem> items;
}

@Data
public class User {
    private List<Order> historyOrders;
}

这导致了经典的循环引用问题。我们的解决方案是：

首先使用@Exclude：

java复制@Data
public class User {
    @ToString.Exclude
    @EqualsAndHashCode.Exclude
    private List<Order> historyOrders;
}

然后为这些类实现自定义的toString()：

java复制@Override
public String toString() {
    return "User(id=" + id + ", name=" + name + ")";
}

最终在团队规范中明确：领域模型避免双向@Data

这个案例给我们的经验是：Lombok虽然方便，但在复杂领域模型中需要谨慎使用@Data注解，特别是在存在关联关系的实体之间。