MapStruct无法找到ProductMapper实现类，Spring启动失败求助

启动错误信息 #

***************************
APPLICATION FAILED TO START
***************************

Description:

Field productMapper in com.example.springshop.service.ImageService required a bean of type 'com.example.springshop.mapper.ProductMapper' that could not be found.


Action:

Consider defining a bean of type 'com.example.springshop.mapper.ProductMapper' in your configuration.

核心相关代码 #

ProductMapper接口 #

package com.example.springshop.mapper;

import java.util.List;

import org.mapstruct.InheritInverseConfiguration;
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;

import com.example.springshop.dto.ProductDTO;
import com.example.springshop.entity.Product;

@Mapper(componentModel = "spring")
public interface ProductMapper {
    @Mapping(target = "id", ignore = true)
    @Mapping(target = "dateOfCreated", ignore = true)
    Product toProduct(ProductDTO productDTO);

    @InheritInverseConfiguration
    ProductDTO fromProduct(Product product);

    List<Product> toProductList(List<ProductDTO> productDTOs);

    List<ProductDTO> fromProductList(List<Product> products);
}

ImageService类 #

package com.example.springshop.service;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import com.example.springshop.dto.ProductDTO;
import com.example.springshop.entity.Image;
import com.example.springshop.entity.Product;
import com.example.springshop.mapper.ProductMapper;

@Service
public class ImageService {
    @Autowired
    private ProductMapper productMapper;

    public void addImageToProduct(ProductDTO productDTO, Image image) {
        Product product = productMapper.toProduct(productDTO);

        image.setProduct(product);
        product.getImages().add(image);
    }
}

build.gradle配置 #

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.1.2'
    id 'io.spring.dependency-management' version '1.1.2'
    id 'com.diffplug.eclipse.apt' version '3.37.2'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
    sourceCompatibility = '20'
}

configurations {
    compileOnly {
        extendsFrom annotationProcessor
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa:3.1.2'
    implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
    compileOnly 'org.projectlombok:lombok'
    developmentOnly 'org.springframework.boot:spring-boot-devtools'
    implementation 'org.springframework.boot:spring-boot-starter-web:3.1.2'
    runtimeOnly 'org.postgresql:postgresql'
    annotationProcessor 'org.projectlombok:lombok'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    implementation 'org.springframework.boot:spring-boot-starter-security:3.1.2'
    implementation 'org.thymeleaf.extras:thymeleaf-extras-springsecurity6:3.1.2.RELEASE'
    implementation 'org.mapstruct:mapstruct:1.5.5.Final'
    annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.5.Final'
    implementation 'io.springfox:springfox-swagger2:3.0.0'
}

tasks.named('test') {
    useJUnitPlatform()
}

排查与解决方案 #

1. 调整注解处理器顺序 #

Lombok与MapStruct共存时，处理器顺序会影响代码生成。将Lombok的注解处理器放在MapStruct之前，确保MapStruct能识别Lombok生成的getter/setter：
修改build.gradle中的annotationProcessor顺序：

annotationProcessor 'org.projectlombok:lombok'
annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.5.Final'

2. 配置Eclipse的注解处理 #

• 打开项目属性，进入Java Compiler > Annotation Processing，勾选Enable annotation processing。
• 进入Annotation Processing > Factory Path，添加mapstruct-processor-1.5.5.Final.jar和lombok.jar到工厂路径。
• 右键target/generated-sources/annotations目录，选择Build Path > Use as Source Folder，确保Eclipse识别该目录为源目录。

3. 解决JDK版本兼容性 #

MapStruct 1.5.5.Final仅支持JDK8-JDK17，而你使用的是JDK20，存在版本不兼容问题：

• 降级JDK到17（Spring Boot 3.x推荐版本）；
• 或升级MapStruct到1.5.6.Final及以上版本（该版本开始支持JDK20）。

4. 清理并重新构建 #

• 在Eclipse中执行Project > Clean，清理项目后重新编译。
• 执行命令行：./gradlew clean build --refresh-dependencies，强制刷新依赖并生成Mapper实现类。

5. 移除不兼容依赖 #

Spring Boot 3.x使用Jakarta EE API，而springfox-swagger2:3.0.0依赖旧的javax API，可能引发冲突。建议移除该依赖，改用SpringDoc OpenAPI：

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

6. 检查循环依赖 #

ImageService依赖ProductMapper，ProductService又依赖ImageService，可能导致Spring初始化异常。建议将字段注入改为构造函数注入：
修改ImageService：

@Service
public class ImageService {
    private final ProductMapper productMapper;

    public ImageService(ProductMapper productMapper) {
        this.productMapper = productMapper;
    }

    // 业务方法不变
}

内容的提问来源于stack exchange，提问作者Матвей Зуев