解决Lombok @RequiredArgsConstructor与@Inject的Javadoc报错

2024-10-01 23:52:56

在使用 Lombok 的 @RequiredArgsConstructor 注解，并尝试通过 onConstructor=@__(@Inject) 在构造函数上添加 @Inject 注解时，你可能会遇到 "cannot find symbol" 的错误，Javadoc 工具提示找不到 __ 这个符号。这个问题多发于 JDK 8 环境，并且与 Maven Javadoc 插件的配置息息相关。让我们来深入探究一下这个问题的根源以及一些可行的解决方案。

JDK 8 与 Lombok 的兼容性问题

Lombok 作为一个优秀的代码简化工具，通过注解在编译时自动生成样板代码，例如构造函数、Getter/Setter 方法等。@RequiredArgsConstructor 注解可以帮助我们自动生成一个包含所有 final 字段和带有 @NonNull 注解字段的构造函数。

而 onConstructor=@__(@Inject) 的作用是在 Lombok 生成的构造函数上添加 @Inject 注解，这在依赖注入框架（例如 Spring）中非常实用。这里的 __ 实际上是 Lombok 内部的一个特殊符号，用于表示需要添加到构造函数上的注解。

然而，JDK 8 对 Lombok 的支持存在一些局限性。在 JDK 8 环境下，Javadoc 工具在处理 Lombok 注解时，可能会遇到无法识别 __ 符号的情况，最终导致编译错误。

解决方案

为了解决这个问题，我们可以尝试以下几种方法：

1. 升级 JDK 版本

最直接有效的解决方案是将 JDK 升级到更高版本，例如 JDK 9 或更高版本。新版本的 JDK 对 Lombok 的支持更加完善，Javadoc 工具通常可以正确识别和处理 __ 符号，避免报错。

2. 使用 delombok

delombok 可以将 Lombok 注解转换成普通的 Java 代码。我们可以先使用 delombok 对代码进行预处理，将 Lombok 注解转换成 Java 代码后再使用 Javadoc 工具生成文档。这样，Javadoc 工具就不会直接处理 Lombok 注解，从而避免了 __ 符号无法识别的问题。

具体操作步骤：

首先，在项目中添加 delombok 依赖。
然后，使用 delombok 命令将代码转换成普通的 Java 代码，例如：

delombok src/main/java -d target/generated-sources/delombok

最后，将 target/generated-sources/delombok 目录添加到 Javadoc 插件的 sourcepath 中，例如：

<plugin>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.10.3</version>
    <configuration>
        <sourcepath>src/main/java;target/generated-sources/delombok</sourcepath>
    </configuration>
</plugin>

3. 使用 Lombok-Javadoc

Lombok-Javadoc 是一个专门为 Lombok 设计的 Javadoc 插件，它可以帮助 Javadoc 工具正确地处理 Lombok 注解，包括 __ 符号。

具体操作步骤：

首先，在项目中添加 Lombok-Javadoc 依赖。
然后，在 Javadoc 插件的配置中指定 Lombok-Javadoc 作为 doclet，例如：

<plugin>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.10.3</version>
    <configuration>
        <doclet>com.github.therapi.apidoc.ApiDoclet</doclet>
        <docletArtifact>
            <groupId>com.github.therapi</groupId>
            <artifactId>apidoc</artifactId>
            <version>0.11.1</version>
        </docletArtifact>
        <useStandardDocletOptions>true</useStandardDocletOptions>
    </configuration>
</plugin>