本文旨在解决使用 lombok 注解（如 `@getter`、`@builder`）的 java bean 类在 sonarqube 代码覆盖率报告中显示未覆盖的问题。通过配置 lombok 生成 `@lombok.generated` 注解，并结合代码覆盖率工具（如 jacoco）对该注解的识别，可以有效地将这些自动生成的代码排除在覆盖率统计之外，从而获得更准确的业务逻辑覆盖率报告。
1. 问题背景：Lombok 与代码覆盖率的冲突
在现代 Java 项目中，Lombok 凭借其强大的注解能力，极大地简化了 POJO（Plain Old Java Object）的编写，例如通过 @Getter、@Setter、@Builder 等注解自动生成大量的样板代码。然而，当项目集成 SonarQube 进行代码质量分析时，这些由 Lombok 在编译期生成的代码往往会成为代码覆盖率报告中的“盲点”。
例如，考虑以下使用 @Getter 和 @Builder 注解的 Java Bean 类：
// MyBody.java
@Getter
@Builder
public class MyBody {
private String accountNumber;
}
// MyHeader.java
@Getter
@Builder
public class MyHeader {
private String username;
private String password;
}
// MyRequest.java
@Builder
@JsonDeserialize(builder = MyRequest.MyRequestBuilder.class)
public class MyRequest {
@JsonProperty("header")
private MyHeader header;
@JsonProperty("body")
private MyBody body;
}即使在测试中充分使用了这些类的实例，例如：
MyBody body = MyBody.builder().accountNumber("12345").build();
MyHeader header = MyHeader.builder().username("someusername").password("somepassword").build();
MyRequest request = MyRequest.builder().body(body).header(header).build();SonarQube 报告中，MyBody.java 和 MyHeader.java 的 @Getter 注解所生成的 getAccountNumber()、getUsername()、getPassword() 方法，以及 @Builder 注解生成的构造器和链式调用方法，可能会被标记为“未覆盖”，导致整体覆盖率下降。这是因为代码覆盖率工具（如 JaCoCo）默认会扫描所有字节码，不区分是手写代码还是由 Lombok 自动生成的代码，而这些生成的代码通常没有直接的测试用例去覆盖它们。
2. 解决方案：配置 Lombok 生成 @lombok.Generated 注解
为了解决这一问题，我们可以利用 Lombok 的配置能力，使其在生成代码时自动添加一个特殊的注解 @lombok.Generated。这个注解是 Lombok 内部用于标记其生成代码的，而主流的代码覆盖率工具（尤其是 JaCoCo 0.8.0 及以上版本）默认会识别并排除带有此注解的方法或类，从而不再将其计入覆盖率报告。
2.1 配置步骤
创建 lombok.config 文件： 在您的项目根目录（对于 Maven 项目，通常是 pom.xml 所在的目录）下创建一个名为 lombok.config 的文件。
-
添加配置属性： 在该文件中添加以下一行配置：
lombok.addLombokGeneratedAnnotation = true
lombok.config 文件的内容示例如下：
# lombok.config # 启用 Lombok 生成 @lombok.Generated 注解 lombok.addLombokGeneratedAnnotation = true
注意： lombok.config 文件的位置非常重要。Lombok 会从当前目录向上查找此文件，直到找到项目根目录。更多关于 Lombok 配置文件的信息，请参考 Lombok 官方文档。
2.2 原理阐述
当 lombok.addLombokGeneratedAnnotation = true 配置生效后，Lombok 在编译时将会在其生成的代码（例如 @Getter 生成的 getter 方法，@Builder 生成的构造器和 builder 方法）上添加 @lombok.Generated 注解。
JaCoCo（作为 SonarQube 默认或常用的 Java 代码覆盖率工具）从 0.8.0 版本开始，默认情况下会自动忽略带有 @javax.annotation.Generated 或 @lombok.Generated 注解的方法和类。这意味着，一旦 Lombok 加上了这个注解，JaCoCo 在生成覆盖率报告时就会自动跳过这些代码，不再将其计入覆盖率统计，从而解决未覆盖的问题。
3. 整合 SonarQube 与 JaCoCo 配置
虽然 lombok.config 配置是核心，但为了确保 SonarQube 能够正确地处理，还需要确认您的项目中的 JaCoCo 和 SonarQube 配置是兼容的。
-
JaCoCo 版本确认： 确保您的 pom.xml 中配置的 JaCoCo Maven 插件版本是 0.8.0 或更高版本。
<build> <plugins> <plugin> <groupId>org.jacoco</groupId> <artifactId>jacoco-maven-plugin</artifactId> <version>0.8.8</version> <!-- 确保版本 >= 0.8.0 --> <executions> <execution> <goals> <goal>prepare-agent</goal> </goals> </execution> <execution> <id>report</id> <phase>prepare-package</phase> <goals> <goal>report</goal> </goals> </execution> </executions> </plugin> </plugins> </build> -
SonarQube 配置： 通常情况下，如果 JaCoCo 版本正确且 Lombok 生成了 @lombok.Generated 注解，SonarQube 无需额外配置即可识别并排除这些代码。SonarQube 会读取 JaCoCo 生成的覆盖率报告 (jacoco.exec 或 jacoco.xml)，而该报告已经排除了被 @lombok.Generated 标记的代码。
如果您遇到特殊情况，可能需要检查 SonarQube 的分析参数，但通常不建议手动排除 Lombok 生成的代码，因为依赖 @lombok.Generated 注解的自动排除更加健壮和易于维护。
4. 注意事项与最佳实践
- 重新构建与分析： 在修改 lombok.config 文件后，务必执行一次完整的 Maven 清理和构建 (mvn clean install)，以确保 Lombok 重新编译代码并生成 @lombok.Generated 注解。之后，再运行 SonarQube 分析 (mvn sonar:sonar)。
- Lombok 版本兼容性： 确保您使用的 Lombok 版本支持 lombok.addLombokGeneratedAnnotation 配置项。较新的 Lombok 版本通常都支持。
- 业务逻辑覆盖： 排除 Lombok 生成的代码是为了让代码覆盖率报告更准确地反映您的业务逻辑的测试覆盖情况，而不是为了降低测试标准。核心业务逻辑和手写代码仍需充分的单元测试覆盖。
- 其他生成代码： 如果项目中还存在其他代码生成工具，并且它们也导致了类似的覆盖率问题，可以考虑它们是否也提供了类似的机制来标记生成代码，以便代码覆盖率工具进行排除。
5. 总结
通过在 lombok.config 文件中简单地添加 lombok.addLombokGeneratedAnnotation = true，我们可以有效地解决 Lombok 生成代码在 SonarQube 代码覆盖率报告中显示未覆盖的问题。这一配置使得 Lombok 在编译时为生成的代码添加 @lombok.Generated 注解，而 JaCoCo 等代码覆盖率工具则会识别并自动排除这些代码，从而提供更准确、更专注于业务逻辑的代码覆盖率统计。这不仅提升了代码质量报告的准确性，也避免了因Lombok生成的样板代码而导致的虚假覆盖率问题。
