本文共 2663 字，大约阅读时间需要 8 分钟。

MapStruct 使用指南

1. 添加依赖

在项目中首先需要添加 MapStruct 的依赖。对于 Maven 和 Gradle 项目，可以通过以下方式添加依赖：

Maven

       
            
     
      org.mapstruct
             
     
      mapstruct
             
     
      1.4.2.Final
         
    
   
       
            
                 
      
       org.apache.maven.plugins
                  
      
       maven-compiler-plugin
                  
      
       3.8.1
                  
                      
       1.8                
       
        1.8
                       
                           
         
         
          org.mapstruct
          
         
          mapstruct-processor
          
         
          1.4.2.Final
          
                        
                   
              
         
    
   

Gradle

dependencies {    implementation 'org.mapstruct:mapstruct:1.4.2.Final'    annotationProcessor 'org.mapstruct:mapstruct-processor:1.4.2.Final'}

2. 定义映射接口

创建一个接口，并使用 @Mapper 注解标注，定义源对象和目标对象之间的映射规则。例如：

import org.mapstruct.Mapper;import org.mapstruct.factory.Mappers;@Mapperpublic interface MyMapper {    MyMapper INSTANCE = Mappers.getMapper(MyMapper.class);    TargetObject map(SourceObject source);}

3. 使用映射方法

在业务逻辑中使用定义的映射接口来转换对象。例如：

public class MyService {    public TargetObject convert(SourceObject source) {        return MyMapper.INSTANCE.map(source);    }}

4. 定义自定义映射方法

如果需要自定义映射逻辑，可以定义一个带有 @Mapping 注解的方法，并在其中指定映射规则。例如：

@Mapperpublic interface MyMapper {    @Mapping(target = "targetProperty", source = "sourceProperty")    @Mapping(target = "targetProperty2", expression = "java(String.valueOf(source.getSourceProperty2()))")    TargetObject map(SourceObject source);}

5. 处理复杂映射

MapStruct 提供了多种注解来支持复杂的映射场景：

使用 @Mapping 注解

@Mapperpublic interface MyMapper {    @Mapping(target = "dateOfBirth", source = "birthYear", qualifiedByName = "yearToCalendar")    TargetObject map(SourceObject source);        @Named("yearToCalendar")    default Date yearToCalendar(int year) {        Calendar calendar = Calendar.getInstance();        calendar.set(year, Calendar.JANUARY, 1);        return calendar.getTime();    }}

支持的映射类型

• 自定义映射：使用 @Mapping 注解的 expression 或 qualifiedByName 属性。
• 集合映射：使用 @IterableMapping 和 @MapMapping 注解。
• 枚举映射：直接映射枚举类型，或使用 @Mapping 注解的 enumNamed 属性。
• 构造函数映射：使用 @Mapping 注解的 constructor 属性。
• 嵌套属性映射：直接映射嵌套对象。
• 反向映射：定义反向映射方法，并使用 @Mapping 注解的 inverse 属性。
• 使用装饰器：使用 @DecoratedWith 注解装饰 Mapper 接口。
• 映射继承：通过继承共享映射配置。
• 预处理和后处理：使用 @BeforeMapping 和 @AfterMapping 注解。
• 上下文参数：使用 @Context 传递额外参数。

6. 集成 Spring

MapStruct 还可以与 Spring 集成，允许在映射器中注入 Spring 管理的 Bean。使用 @Mapper(componentModel = "spring") 注解以指定 Spring 作为组件模型：

@Mapper(componentModel = "spring")public interface MyMapper {    TargetObject map(SourceObject source);}

这样，MapStruct 映射器就可以作为 Spring Bean 进行自动装配。

通过使用 MapStruct，您可以减少手动编写的样板代码，提高开发效率，并减少因手动映射而产生的错误。