使用Gradle时MapStruct无法识别Lombok的@Builder注解

核心配置要点 #

要让MapStruct识别Lombok生成的Builder，关键是保证编译阶段MapStruct能获取到Lombok处理后的类元数据，Gradle中需调整注解处理器的依赖与执行顺序。

1. 依赖配置 #

在build.gradle（Groovy DSL）或build.gradle.kts（Kotlin DSL）中添加以下依赖：

Groovy DSL 示例

dependencies {
    // 核心依赖
    implementation 'org.mapstruct:mapstruct:1.5.5.Final'
    implementation 'org.projectlombok:lombok:1.18.30'
    
    // 注解处理器依赖
    annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.5.Final'
    annotationProcessor 'org.projectlombok:lombok:1.18.30'
    // 自动处理处理器顺序的绑定依赖（推荐）
    annotationProcessor 'org.projectlombok:lombok-mapstruct-binding:0.2.0'
}

Kotlin DSL 示例

dependencies {
    implementation("org.mapstruct:mapstruct:1.5.5.Final")
    implementation("org.projectlombok:lombok:1.18.30")
    
    annotationProcessor("org.mapstruct:mapstruct-processor:1.5.5.Final")
    annotationProcessor("org.projectlombok:lombok:1.18.30")
    annotationProcessor("org.projectlombok:lombok-mapstruct-binding:0.2.0")
}

2. 处理器顺序控制（可选，若用绑定依赖可跳过） #

如果不使用lombok-mapstruct-binding，需手动指定Lombok先于MapStruct执行：

tasks.withType(JavaCompile) {
    options.compilerArgs += [
        '-Amapstruct.defaultComponentModel=spring', // Spring环境可选配置
        '-Xlint:unchecked',
        '-Xlint:deprecation'
    ]
    // 调整处理器顺序，确保Lombok先执行
    options.annotationProcessorPath = files(
        configurations.annotationProcessor.filter { it.name.contains('lombok') },
        configurations.annotationProcessor.filter { it.name.contains('mapstruct') }
    )
}

3. 代码示例 #

实体类（带@Builder）

@Data
@Builder
public class User {
    private Long id;
    private String username;
    private String email;
}

MapStruct Mapper接口

@Mapper(componentModel = "spring")
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);

    @Mapping(target = "id", ignore = true)
    User toUser(UserDto userDto);

    UserDto toUserDto(User user);
}

常见问题排查 #

• 版本兼容：MapStruct 1.5.x 搭配 Lombok 1.18.x 为稳定组合
• IDE设置：IntelliJ IDEA需开启Enable annotation processing（路径：设置 -> Build, Execution, Deployment -> Compiler -> Annotation Processors）
• 缓存清理：执行./gradlew clean build --refresh-dependencies清理缓存后重新构建

内容的提问来源于stack exchange，提问作者spartanhooah