当前位置：首页 > news >正文

MapStruct Plus 的依赖分析

news 2026/7/26 11:57:46

MapStruct Plus 的依赖分析核心在于两点：版本演进带来的依赖变化和避免与原生 MapStruct 的依赖冲突。

🚀 版本演进：1.4.0 是分水岭

MapStruct Plus 的依赖管理在1.4.0 版本前后有重大变化：

1.4.0 版本之前：mapstruct-plus或mapstruct-plus-spring-boot-starter会传递依赖hutool等工具库。
1.4.0 版本及之后（推荐）：为了更轻量，项目移除了 Hutool 等所有非 MapStruct 的外部依赖。打包后的体积更小，但如果你需要使用Map与对象之间的转换功能，则需要手动额外引入hutool-core依赖包。

📦 核心依赖：内嵌 MapStruct，避免冲突

MapStruct Plus内嵌了 MapStruct，因此在使用时，你不需要也不应该在项目中再单独引入任何org.mapstruct的依赖。

同时，你还需要排查并排除项目其他依赖（如springfox-swagger2）中传递的 MapStruct 依赖，以防止版本冲突导致编译或运行时异常。

💻 具体依赖配置（以 Maven 为例）

1. 引入 MapStruct Plus 核心依赖

Spring Boot 环境（推荐）：直接使用封装好的Starter。

xml

<properties> <mapstruct-plus.version>1.5.0</mapstruct-plus.version> <!-- 使用最新稳定版本 --> </properties> <dependencies> <dependency> <groupId>io.github.linpeilie</groupId> <artifactId>mapstruct-plus-spring-boot-starter</artifactId> <version>${mapstruct-plus.version}</version> </dependency> </dependencies>

非 Spring Boot 环境：需要引入核心包和注解处理器。

xml

<dependencies> <dependency> <groupId>io.github.linpeilie</groupId> <artifactId>mapstruct-plus</artifactId> <version>${mapstruct-plus.version}</version> </dependency> </dependencies> <!-- 在 maven-compiler-plugin 中配置注解处理器 -->

2. 可选：为 Map 转换功能添加 Hutool 依赖

如果你使用了 1.4.0+ 版本，并且需要进行Map与Object的转换，则需要手动添加：

xml

<dependency> <groupId>cn.hutool</groupId> <artifactId>hutool-core</artifactId> <version>最新版本</version> <!-- 请使用与你项目兼容的最新版本 --> </dependency>

⚠️ 与 Lombok 整合的注意事项

由于 MapStruct Plus 和 Lombok 都是通过注解处理器工作的，为确保它们协同工作，需要在maven-compiler-plugin的annotationProcessorPaths中同时声明两者。

xml

<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.8.1</version> <configuration> <annotationProcessorPaths> <!-- 1. 先声明 Lombok --> <path> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <version>${lombok.version}</version> </path> <!-- 2. 再声明 MapStruct Plus 处理器 --> <path> <groupId>io.github.linpeilie</groupId> <artifactId>mapstruct-plus-processor</artifactId> <version>${mapstruct-plus.version}</version> </path> </annotationProcessorPaths> </configuration> </plugin>

🐛 常见问题与解决方案

Couldn't retrieve @Mapper annotation异常：几乎都是因为项目中存在 MapStruct 依赖冲突。解决方法是排除所有其他依赖传递进来的org.mapstruct相关包。
NoSuchMethodError异常：在多模块项目中，每个模块都可能生成同名的ConvertMapperAdapter类，导致类加载器加载了错误的类。解决方法是为每个模块通过配置指定不同的adapterPackage路径。
转换接口未生成：检查是否因 IDE 设置（如“Show Excluded Files”）而看不到生成目录；或排查spring-boot-devtools依赖，它可能干扰类加载器导致生成失败。