mapstruct中的@Mapper注解的基本用法

2025-06-14 03:50
文章标签 用法 基本 注解 mapstruct mapper

本文主要是介绍mapstruct中的@Mapper注解的基本用法，希望对大家解决编程问题提供一定的参考价值，需要的开发者们随着小编来一起学习吧！

《mapstruct中的@Mapper注解的基本用法》在MapStruct中,@Mapper注解是核心注解之一,用于标记一个接口或抽象类为MapStruct的映射器（Mapper）,本文给大家介绍ma...

在MapStruct中，@Mapper注解是核心注解之一，用于标记一个接口或抽象类为MapStruct的映射器（Mapper）。MapStruct会在编译时自动生成该接口的实现类，完成对象之间的属性映射。以下是对@Mapper注解的详细解析：

1. 基本用法

@Mapper注解可以单独使用，也可以配合其他属性进行配置。以下是一个简单的示例：

import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.factory.Mappers;
@Mapper
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);
    @Mapping(source = "username", target = "name")
    UserDTO toUserDTO(User user);
}
  • @Mapper：标记接口为MapStruct的映射器。
  • Mappers.getMapper(UserMapper.class)：获取MapStruct自动生成的映射器实例。
  • @Mapping：指定属性映射规则（例如将User的username属性映射到UserDTO的name属性）。

2. 常用属性

@Mapper注解支持多种属性，用于配置映射器的行为：

(1) componentModel

指定生成的映射器实现类的组件模型，便于与其他框架（如Spring、CDI）集成。

可选值： default：默认模型，不依赖任何框架。

  • spring：生成的映射器实现类会带有@Component注解，便于Spring管理。
  • cdi：生成的映射器实现类会带有@ApplicationScoped注解，便于CDI管理。
  • jsr330：生成的映射器实现类会带有@Javax.inject.Named和@javax.inject.Singleton注解。

示例：

@Mapper(componentModel = "spring")
public interface UserMapper {
    UserMapper www.chinasem.cnINSTANCE = Mappers.getMapper(UserMapper.class);
    // ...
}

(2) uses

指定其他映射器或工具类，用于在映射过程中调用。

示例：

@Mapper(uses = {DateMapper.class})
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);
    // ...
}

(3) implementationName 和 implementationPackage

  • implementationName：指定生成的映射器实现类的名称（默认为接口名+Impl）。
  • implementationPackage：指定生成的映射器实现类的包名（默认为接口所在编程包）。

示例：

@Mapper(implementationName = "CustomUserMapperImpl", implementationPackage = "com.example.mappers")
public interface UserMapper {
    // ...
}

(4) unmappedTargetPolicy

指定当目标对象有未映射的属性时的处理策略。

可选值：

  • ERROR：抛出异常（默认值）。
  • WARN：生成警告日志。
  • IGNORE：忽略未映射的属性。

示例：

@Mapper(unmappedTargetPolicy = ReportingPolicy.IGNORE)
public interface UserMapper {
    // ...
}

(5) injectionStrategy

指定依赖注入的策略。

可选值：

  • FIELD：通过字段注入（默认值）。
  • CONSTRUCTOR：通过构造函数注入。
  • METHOD：通过方法注入。

示例：

@Mapper(componentModel = "spring", injectionStrategy = InjectionStrategy.CONSTRUCTOR)
public interface UserMapper {
    // ...
}

3. 高级用法

(1) 结合@MapperConfig

可以通过@MapperConfig定义全局配置，然后在@Mapper中引用。

示例：

@MapperConfig(componentModel = "spring", unmappedTargetPolicy = ReportingPolicy.IGNORE)
public interface CommonMapperConfig {
}
@Mapper(config = CommonMapperConfig.class)
public interface UserMapper {
    // ...
}

(2) 自定义方法

可以在映射器接口中定义自定义方法，MapStruct会调用这些方法完成复杂的映射逻辑。

示例：

@Mapper
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);
    @Mapping(target = "fullName", expression = "java(user.getFirstName() + \" \" + user.getLastName())")
    UserDTO toUserDTO(User user);
    default String formatDate(Date date) {
        // 自定义日期格式化逻辑
        return new SimpleDateFormat("yyyy-MM-dd").format(date);
    }
}

4. 注意事项

依赖配置：

  • 确保项目中包含MapStruct的依赖和注解处理器（mapstruct和mwww.chinasem.cnapstruct-processor）。
  • 如果使用Lombok，确保Lombok的版本兼容，并在构建工具（如Maven或Gradle）中正确配置。

映射规则：

  • 如果源对象和目标对象的属性名相同，MapStruct会自动映射。
  • 如果属性名不同，需要通过@Mapping注解显式指定。

性能：

  • MapStruct生成的映射代码是类型安全的，且在编译时完成，性能优于运行时反射的映射工具（如Apache Commons BeanUtils）。

5. 总结

@Mapper注解是MapStruct的核心，通过它可以：

  • 定义映射器接口。
  • 配置映射器的行为（如组件模型、未映射属性的处理策略等）。
  • 结合其他注解（如@Mapping）完成复杂的属性映射。
  • 与其他框架（如Spring）无缝集成。

通过合理使用@Mapper注解及其属性，可以大大简化对象之间的映射逻辑，提高开发效率和代码质量。

6. 编译异常处理

针对MapStruct项目编译异常问题，可从依赖配置、IDE设置、代码规范及版本兼容性四个维度进行排查和解决，以下是具体分析和建议：

  • 现象：缺少必要的注解处理器依赖，如org.mapstruct:mapstruct-processor，导致编译时无法生成Mapper类。
  • 解决方案：
    • Maven项目：在pom.XML中添加MapStruct核心库和处理器依赖，例如：
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct</artifactId>
    <version>1.5.3.Final</version>
</dependency>
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct-processor</artifactId>
    <version>1.5.3.Final</version>
    <scope>provided</scope>
</dependency>
- **Gradle项目**：在`build.gradle`中添加：
implementation 'org.mapstruct:mapstruct:1.5.3.Final'
annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.3.Final'

IDE设置问题

  • 现象：IDE未启用注解处理器或缓存异常，导致编译时无法正确处理MapStruct注解。
  • 解决方案：
    • IntelliJ IDEA：打开“File”菜单，选择“Settings”，导航至“Build, Execution, Deployment” -> “Compiler” -> “Annotation Processors”，勾选“Enable annotation processing”选项，并清理IDE缓存后重新构建项目。

代码规范问题

  • 现象：Mapper接口定义错误，如方法签名不匹配或缺少必要注解，导致编译失败。
  • 解决方案：
    • 验证Mapper接口：确保接口符合MapStruct规范，例如：
@Mapper
public interface UserMapper {
    UserDto userToUserDto(User user);
}
- **检查属性映射**：如果源对象和目标对象的属性名不同，需要通过`@Mapping`注解显式指定，例如：
@Mapper
public interface UserMapper {
    @Mapping(source = "username", target = "name")
    UserDto userToUserDto(User user);
}

版本兼容性问题

  • 现象：MapStruct版本与其他依赖（如Lombok）不兼容，导致编译异常。
  • 解决方案：
    • 升级MapStruct版本：尝试升级至最新稳定版本，例如：
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct</artifactId>
    <version>1.6.0.Final</version>
</dependency>
- **解决Lombok冲突**：如果项目中同时使用Lombok和MapStruct，特别是使用Lombok的`@Builder`注解时，可能导致`@AfterMapping`不生效。对于Lombok版本1.18.16或更高版本，需添加`lombok-mapstruct-binding`依赖：
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok-mapstruct-binding</artifactId>
    <version>0.2.0</version>
</dependency>

其他可能的问题及解决方案

  • 未映射的目标属性：检查源对象和目标对象，确保存在对应的属性，或使用@Mapping(target = "property", ignore = true)忽略不需要映射的属性。
  • 枚举类型映射：自定义映射方法，例如：
@Mapper
public interface EnumConverter {
    default TargetEnum toTargetEnum(SourceEnum sourceEnum) {
        if (sourceEnum == null) {
            return null;
        }
        switch (sourceEnum) {
            case SOURCE_VALUE1:
                return TargetEnum.TARGET_VALUE1;
            case SOURCE_VALUE2:
                return TargetEnum.TARGET_VALUE2;
            default:
                throw new IllegalArgumentException("Unknown enum type: " + sourceEnum);
        }
    }
}
  • 集合类型映射：使用@Iterhttp://www.chinasem.cnableMapping注解明确指定集合类型的映射方式。
  • 循环引用问题：使用@Context注解通过传递上下文对象来避免无限递归。

到此这篇关于mapstruct中的@Mapper注解的基本用法的文章就介绍到这了,python更多相关mapstruct @Mapper注解内容请搜索China编程(www.chinasem.cn)以前的文章或继续浏览下面的相关文章希望大家以后多多支持编程China编程(www.chinasem.cn)！

这篇关于mapstruct中的@Mapper注解的基本用法的文章就介绍到这儿，希望我们推荐的文章对编程师们有所帮助！


http://www.chinasem.cn/article/1155052。

相关文章

springboot自定义注解RateLimiter限流注解技术文档详解

springboot自定义注解RateLimiter限流注解技术文档详解

《springboot自定义注解RateLimiter限流注解技术文档详解》文章介绍了限流技术的概念、作用及实现方式,通过SpringAOP拦截方法、缓存存储计数器,结合注解、枚举、异常类等核心组件,... 目录什么是限流系统架构核心组件详解1. 限流注解 (@RateLimiter)2. 限流类型枚举 (
阅读更多...
Java Spring的依赖注入理解及@Autowired用法示例详解

Java Spring的依赖注入理解及@Autowired用法示例详解

《JavaSpring的依赖注入理解及@Autowired用法示例详解》文章介绍了Spring依赖注入（DI）的概念、三种实现方式（构造器、Setter、字段注入）,区分了@Autowired（注入... 目录一、什么是依赖注入（DI）？1. 定义2. 举个例子二、依赖注入的几种方式1. 构造器注入（Con
阅读更多...
详解MySQL中JSON数据类型用法及与传统JSON字符串对比

详解MySQL中JSON数据类型用法及与传统JSON字符串对比

《详解MySQL中JSON数据类型用法及与传统JSON字符串对比》MySQL从5.7版本开始引入了JSON数据类型,专门用于存储JSON格式的数据,本文将为大家简单介绍一下MySQL中JSON数据类型... 目录前言基本用法jsON数据类型 vs 传统JSON字符串1. 存储方式2. 查询方式对比3. 索引
阅读更多...
Java中使用 @Builder 注解的简单示例

Java中使用 @Builder 注解的简单示例

《Java中使用@Builder注解的简单示例》@Builder简化构建但存在复杂性,需配合其他注解,导致可变性、抽象类型处理难题,链式编程非最佳实践,适合长期对象,避免与@Data混用,改用@G... 目录一、案例二、不足之处大多数同学使用 @Builder 无非就是为了链式编程，然而 @Builder
阅读更多...
spring中的@MapperScan注解属性解析

spring中的@MapperScan注解属性解析

《spring中的@MapperScan注解属性解析》@MapperScan是Spring集成MyBatis时自动扫描Mapper接口的注解,简化配置并支持多数据源,通过属性控制扫描路径和过滤条件,利... 目录一、核心功能与作用二、注解属性解析三、底层实现原理四、使用场景与最佳实践五、注意事项与常见问题六
阅读更多...
MySql基本查询之表的增删查改+聚合函数案例详解

MySql基本查询之表的增删查改+聚合函数案例详解

《MySql基本查询之表的增删查改+聚合函数案例详解》本文详解SQL的CURD操作INSERT用于数据插入（单行/多行及冲突处理）,SELECT实现数据检索（列选择、条件过滤、排序分页）,UPDATE... 目录一、Create1.1 单行数据 + 全列插入1.2 多行数据 + 指定列插入1.3 插入否则更
阅读更多...
C#连接SQL server数据库命令的基本步骤

C#连接SQL server数据库命令的基本步骤

《C#连接SQLserver数据库命令的基本步骤》文章讲解了连接SQLServer数据库的步骤,包括引入命名空间、构建连接字符串、使用SqlConnection和SqlCommand执行SQL操作,... 目录建议配合使用：如何下载和安装SQL server数据库-CSDN博客1. 引入必要的命名空间2.
阅读更多...
全面掌握 SQL 中的 DATEDIFF函数及用法最佳实践

全面掌握 SQL 中的 DATEDIFF函数及用法最佳实践

《全面掌握SQL中的DATEDIFF函数及用法最佳实践》本文解析DATEDIFF在不同数据库中的差异,强调其边界计算原理,探讨应用场景及陷阱,推荐根据需求选择TIMESTAMPDIFF或inte... 目录1. 核心概念：DATEDIFF 究竟在计算什么？2. 主流数据库中的 DATEDIFF 实现2.1
阅读更多...
MySQL中的LENGTH()函数用法详解与实例分析

MySQL中的LENGTH()函数用法详解与实例分析

《MySQL中的LENGTH()函数用法详解与实例分析》MySQLLENGTH()函数用于计算字符串的字节长度,区别于CHAR_LENGTH()的字符长度,适用于多字节字符集（如UTF-8）的数据验证... 目录1. LENGTH()函数的基本语法2. LENGTH()函数的返回值2.1 示例1：计算字符串
阅读更多...
Java中的数组与集合基本用法详解

Java中的数组与集合基本用法详解

《Java中的数组与集合基本用法详解》本文介绍了Java数组和集合框架的基础知识,数组部分涵盖了一维、二维及多维数组的声明、初始化、访问与遍历方法,以及Arrays类的常用操作,对Java数组与集合相... 目录一、Java数组基础1.1 数组结构概述1.2 一维数组1.2.1 声明与初始化1.2.2 访问
阅读更多...

Copyright China编程 23002807@qq.com

沪ICP备2023033072号-2