MapStruct 实体类转换工具，看这一篇就够了！

前言

DTO（Data Transfer Object）：数据传输对象，这个概念来源于J2EE的设计模式，原来的目的是为了EJB的分布式应用提供粗粒度的数据实体，以减少分布式调用的次数，从而提高分布式调用的性能和降低网络负载，但在这里，泛指用于展示层与服务层之间的数据传输对象。
DO（Domain Object）：领域对象，就是从现实世界中抽象出来的有形或无形的业务实体。

说明：在一个成熟的工程中，尤其是现在的分布式系统中，应用与应用之间，还有单独的应用细分模块之后，DO 一般不会让外部依赖，这时候需要在提供对外接口的模块里放 DTO 用于对象传输，也即是 DO 对象对内，DTO对象对外，DTO 可以根据业务需要变更（只需部分字段或字段名不同等），并不需要映射 DO 的全部属性。

这种对象与对象之间的互相转换，就需要有一个专门用来解决转换问题的工具，毕竟每一个字段都 get/set 会很麻烦。

MapStruct 就是这样的一个属性映射工具，只需要定义一个 Mapper 接口，MapStruct 就会自动实现这个映射接口，避免了复杂繁琐的映射实现。MapStruct官网地址： http://mapstruct.org/

MapStruct是一个用于Java的代码生成库，它基于注解处理器在编译时生成类型安全且高性能的对象映射代码。MapStruct可以帮助开发者减少手动编写繁琐的JavaBean之间的转换代码，提高代码的可读性和维护性。

一、什么是 MapStruct

MapStruct 核心概念

MapStruct是一个Java注解处理器，它的主要功能是自动生成类型安全、高性能且无依赖的bean映射代码。这个工具基于“约定优于配置”的原则，极大地简化了Java Bean类型之间的映射实现过程。

在多层架构的应用中，经常需要在不同的对象模型之间进行转换，例如在持久层的实体和传输层的DTO（Data Transfer Object，数据传输对象）之间。手动编写这种映射代码是一项繁琐且容易出错的任务。MapStruct通过自动化的方式解决了这个问题，它可以在编译时生成映射代码，从而保证了高性能、快速的开发反馈以及严格的错误检查。

具体来说，使用MapStruct时，开发者只需要定义一个接口，并在接口中定义转换方法。然后，MapStruct会自动生成实现这些方法的代码。这些生成的代码使用纯方法调用，因此速度快、类型安全且易于理解。

MapStruc主要特性

1、类型安全：MapStruct在编译时生成映射代码并进行类型检查，如果源对象和目标对象的属性不匹配，会在编译阶段就报错。

2、性能优秀：由于MapStruct在编译时就生成了映射代码，运行时无需通过反射进行属性拷贝，因此性能较高。

3、灵活性：MapStruct支持复杂的映射，如嵌套映射、集合映射、自定义转换规则等。

4、简洁性：MapStruct使用注解来定义映射规则，使得映射规则的定义更加直观和简洁。

5、无依赖：MapStruct不依赖于任何第三方库，可以很容易地集成到任何项目中。

6、集成Spring：MapStruct也可以与Spring框架集成，允许在映射器中注入Spring管理的bean。

使用MapStruct，开发者只需要定义一个接口，并在接口中声明源对象和目标对象之间的映射关系，MapStruct会在编译时自动生成映射实现类。这极大地提高了代码的可读性和可维护性，同时也避免了手动编写繁琐的转换代码。

二、MapStruct和BeanUtils区别

MapStruct和BeanUtils都是Java中常用的对象属性映射工具，但它们在使用方式和性能上有一些区别。

「1、使用方式：」BeanUtils：使用反射机制进行属性拷贝，使用简单，无需写额外的映射代码。 MapStruct：需要定义映射接口，在编译阶段生成映射实现类，使用注解来定义源对象和目标对象之间的映射关系。

「2、性能：」BeanUtils：由于使用了反射机制，性能较低。 MapStruct：在编译阶段就生成了映射代码，运行时无需通过反射进行属性拷贝，因此性能较高。

「3、灵活性和安全性：」BeanUtils：由于是动态映射，如果源对象和目标对象的属性不匹配，可能会在运行时出现错误。 MapStruct：在编译阶段就进行了类型检查，如果源对象和目标对象的属性不匹配，会在编译阶段就报错，提高了类型安全性。另外，也支持复杂的映射，如嵌套映射、集合映射等。

先看一个案例：

@Mapper
public interface CarMapper {
  
    @BeanMapping(resultType = CarDto.class, ignoreByDefault = true, mappingControl = MappingControl.FILTER)
    @Mapping(target = "color", ignore = true)
    @Mapping(source = "model", target = "modelName")
    @Mapping(condition = "java(source.getAge() >= 18)", target = "isAdult")
    CarDto map(Car car);
  
}

在这个例子中，我们定义了一个名为CarMapper的映射器接口，并使用了@Mapper注解将它标记为MapStruct映射器。然后，我们在映射方法上使用了@BeanMapping注解，并提供了以下配置：

resultType = CarDto.class：指定映射方法的返回类型为CarDto。
ignoreByDefault = true：在目标类型CarDto中忽略所有未映射的属性。
mappingControl = MappingControl.FILTER：如果存在未匹配的属性，过滤它们而不报告错误或警告。

接下来，我们使用了@Mapping注解，对特定属性进行了额外的配置：

target = “color”, ignore = true：忽略源对象的color属性，在目标对象CarDto中不进行映射。
source = “model”, target = “modelName”：将源对象的model属性映射到目标对象的modelName属性。
condition = “java(source.getAge() >= 18)”：添加条件判断，只有当源对象的age属性大于等于18时，才进行映射，并将结果映射到目标对象的isAdult属性。

通过这些配置，我们能够灵活地控制映射方法的行为。可以根据需求指定返回类型、忽略属性、设置映射控制策略，并添加条件判断来决定是否执行映射操作。

三、MapStruct的使用方法

添加依赖

在你的pom.xml文件中添加MapStruct的依赖：

org.mapstruct:mapstruct：包含了一些必要的注解，例如@Mapping。若我们使用的JDK版本高于1.8，当我们在pom里面导入依赖时候，建议使用坐标是：org.mapstruct:mapstruct-jdk8，这可以帮助我们利用一些Java8的新特性。
org.mapstruct:mapstruct-processor：注解处理器，根据注解自动生成mapper的实现。

<!--mapstruct核心-->
<dependency>
    <groupId>org.mapstruct</groupId>
  	<!-- jdk8以下就使用mapstruct -->
    <artifactId>mapstruct-jdk8</artifactId>
    <version>1.5.5.Final</version>
</dependency>
<!--mapstruct编译-->
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct-processor</artifactId>
    <version>1.5.5.Final</version>
</dependency>

基本映射

在生成的方法实现中，源类型（例如Person）的所有可读属性都将被复制到目标类型（例如PersonDto）的相应属性中：

当一个属性与其目标实体对应的名称相同时，它将被隐式映射。
当属性在目标实体中具有不同的名称时，可以通过@Mapping注释指定其名称。

如果不指定@Mapping，默认映射name相同的field
如果映射的对象field name不一样，通过 @Mapping 指定。
忽略字段加@Mapping#ignore() = true

Person类

@Data
public class Person {

    private String id;

    private String name;

    private BigDecimal source;

    private double height;

    private Date createTime;
	
}

PersonDto类

@Data
public class PersonDTO {

    private Long id;

    private String personName;

    private String source;

    private String height;
    
}

定义Mapper接口

定义一个Mapper接口，这个接口将包含你想要转换的方法。

例如，假设你有两个类，Person和PersonDto，你想要将Person对象转换为PersonDto对象，那么你可以这样定义你的Mapper：

@Mapper
public interface PersonMapper {
  
    PersonMapper INSTANCE = Mappers.getMapper( PersonMapper.class );

		@Mapping(target = "name", source = "personName")
	  @Mapping(target = "id", ignore = true) // 忽略id，不进行映射
		PersonDto personToPersonDto(Person person);

}

使用Mapper

当你已经定义了Mapper接口后，你就可以在你的代码中使用它了：

@Test
public void test(){
     Person person = new Person();
  	 person.setId("001");
     person.setAge(18);
     person.setName("张三");
     person.setHeight(170.5);
     person.setSource(new BigDecimal("100"));

     PersonDTO dto = PersonMapper.INSTANCT.conver(person);

     System.out.println(dto);
    // PersonDTO(id=null, personName=张三, age=18, source=100, height=170.5)
}

componentModel 属性

@Mapper 注解的 componentModel 属性用于指定自动生成的接口实现类的组件类型，这个属性支持四个值：

default: 这是默认的情况，mapstruct 不使用任何组件类型, 可以通过Mappers.getMapper(Class)方式获取自动生成的实例对象。

@Mapper
public interface PersonMapper {

    PersonMapper INSTANCE = Mappers.getMapper( PersonMapper.class );
    
    PersonDto personToPersonDto(Person person);

}

@Service
public class PersonService {
    
  	public PersonDto convert(Person person){
      PersonDto dto = PersonMapper.INSTANCE.personToPersonDto(person);
      return dto;
    }
   
}

cdi: the generated mapper is an application-scoped CDI bean and can be retrieved via @Inject
spring: 生成的实现类上面会自动添加一个@Component注解，可以通过Spring的 @Autowired或者@Resource方式进行注入

@Mapper(componentModel = "spring")
public interface PersonMapper {

    @Mapping(source = "name", target = "fullName")
    PersonDto personToPersonDto(Person person);

}

@Service
public class PersonService {

    @Autowired
  	private PersonMapper personMapper;
    
  	public PersonDto convert(Person person){
      PersonDto dto = personMapper.personToPersonDto(person);
      return dto;
    }
   
}

jsr330: 生成的实现类上会添加@javax.inject.Named 和@Singleton注解，可以通过 @Inject注解获取

nullValueCheckStrategy属性

是否在生成的实现类中，对每一个属性进行null检查，可选值有两个：ON_IMPLICIT_CONVERSION（默认值）和 ALWAYS 。

ALWAYS

ALWAYS 表示在赋值之前，对每一个属性进行!= null的检查。

@Mapper(nullValueCheckStrategy = NullValueCheckStrategy.ALWAYS)
public interface PersonMapper {

    PersonDto personToPersonDto(Person person);

}

ON_IMPLICIT_CONVERSION

ON_IMPLICIT_CONVERSION则表示直接进行赋值，不进行 != null 判断。

@Mapper(nullValueCheckStrategy = NullValueCheckStrategy.ON_IMPLICIT_CONVERSION)
public interface PersonMapper {

    PersonDto personToPersonDto(Person person);

}

nullValuePropertyMappingStrategy属性

指定当源属性为null或者不存在时目标属性生成值的策略，可选值有：

SET_TO_NULL（默认值）

当源属性为null或者不存在时，设置目标属性的值为null。

SET_TO_DEFAULT

根据源属性的类型，设置指定的默认值。

源属性是List，则默认值是ArrayList；

源属性是String，则默认值是""；源属性是基本类型，则默认值是0或者false；

源属性是Map，则默认值是LinkedHashMap；

源属性是数组，则默认值是空数组。

IGNORE

如果源属性是null或者不存在，则不会将null赋值给目标属性，目标属性是什么值就保持什么值。

指定默认值

在@Mapper接口类里面的转换方法上添加@Mapping注解
target() 必须添加，source()可以不添加，则直接使用defaultValue

@Mapping(target = "describe", defaultValue = "默认值")
PersonDTO conver(Person person);

自定义映射

在某些情况下，可能需要自定义字段映射。可以通过在@Mapping注解中使用expression或qualifiedByName参数来实现这一点。

expression

expression: 这个参数允许你使用Java表达式来定义字段映射。这在源和目标字段之间需要一些特定逻辑时非常有用。

注意：这个属性不能与source()、defaultValue()、defaultExpression()、qualifiedBy()、qualifiedByName()或constant()一起使用。

例如：

@Mapper
public interface OrderMapper {
    @Mapping(target = "orderDate", expression = "java(new java.text.SimpleDateFormat(\"yyyy-MM-dd\").format(order.getCreationDate()))")
    OrderDto orderToOrderDto(Order order);
}

在这个例子中，orderToOrderDto方法将Order的creationDate字段（类型为Date）转换为OrderDto的orderDate字段（类型为String），并且使用了特定的日期格式。

qualifiedByName和@namd

qualifiedByName: 这个参数允许你引用一个具有@Named注解的方法作为自定义的映射逻辑。例如：

@Mapper
public interface OrderMapper {
  
    @Mapping(target = "customerName", source = "customer", qualifiedByName = "fullName")
    OrderDto orderToOrderDto(Order order);

		@Named("fullName")
		default String customerToString(Customer customer) {
    		return customer.getFirstName() + " " + customer.getLastName();
		}

}

在这个例子中，orderToOrderDto方法将Order的customer字段（类型为Customer）转换为OrderDto的customerName字段（类型为String），并且使用了customerToString方法来获取全名。

映射方法级别的详细配置

从MapStruct 1.5开始，可以使用@BeanMapping注解在MapStruct中用于在映射方法级别提供更详细的配置。这个注解有许多参数可以使用，例如，你可以选择在更新时忽略null值。

以下是一些常见的使用场景：

resultType: 这个参数允许你指定映射方法的返回类型。这在目标类型可以是多个实现类时非常有用。如果目标类型有多个实现类，并且你希望在映射时使用特定的实现类。通过指定resultType，你可以确保生成的映射代码使用正确的目标类型

@BeanMapping(resultType = CarDto.class)
CarDto map(Car car);

qualifiedBy和qualifiedByName: 这两个参数允许你引用一个具有@Qualifier或@Named注解的方法作为自定义的映射逻辑。

@BeanMapping(qualifiedByName = "fullName")
PersonDto personToPersonDto(Person person);

@Named("fullName")
default String customerToString(Customer customer) {
    return customer.getFirstName() + " " + customer.getLastName();
}

ignoreByDefault: 这个参数允许你忽略所有未明确映射的属性。然后，你可以使用@Mapping注解来明确需要映射的属性。

@BeanMapping(ignoreByDefault = true)
@Mapping(target = "name", source = "fullName")
PersonDto personToPersonDto(Person person);

nullValuePropertyMappingStrategy: 这个参数允许你指定当源属性为null时应如何处理目标属性。例如，你可以选择是否在源属性为null时调用目标的setter方法。

@BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
PersonDto personToPersonDto(Person person);

集合映射

MapStruct也支持集合的映射，你可以很方便地将一个对象的集合转换为另一个对象的集合。

@Mapper
public interface CarMapper {
    List<CarDto> carsToCarDtos(List<Car> cars);
}

在这个例子中，carsToCarDtos方法将List转换为List。

枚举映射

MapStruct 的 @ValueMapping 注解是用来映射枚举值的。这个注解只能在 @Mapper 的接口或抽象类中使用。下面是一个简单的例子，展示了如何使用 @ValueMapping 在两个枚举类型之间进行映射：

首先，我们定义两个枚举类型：

public enum SourceEnum {
    TYPE_A,
    TYPE_B,
    TYPE_C
}

public enum TargetEnum {
    TYPE_X,
    TYPE_Y,
    TYPE_Z
}

然后，我们创建一个映射器接口并使用 @ValueMapping：

@Mapper
public interface EnumMapper {
    @ValueMappings({
        @ValueMapping(source = "TYPE_A", target = "TYPE_X"),
        @ValueMapping(source = "TYPE_B", target = "TYPE_Y"),
        @ValueMapping(source = "TYPE_C", target = "TYPE_Z")
    })
    TargetEnum sourceToTarget(SourceEnum sourceEnum);
}

在上述代码中，我们定义了一个 sourceToTarget 方法，它将 SourceEnum 对象映射到 TargetEnum 对象。@ValueMapping 注解指定了源枚举值到目标枚举值的映射。

此外，MapStruct 还提供了特殊的源/目标值 NULL 和 ANY，可以用于处理源枚举值为 null 或未映射的情况。例如：

@Mapper
public interface EnumMapper {
    @ValueMappings({
        @ValueMapping(source = "TYPE_A", target = "TYPE_X"),
        @ValueMapping(source = "TYPE_B", target = "TYPE_Y"),
        @ValueMapping(source = "TYPE_C", target = "TYPE_Z"),
        @ValueMapping(source = "NULL", target = "TYPE_Z"),
        @ValueMapping(source = "ANY", target = "TYPE_X")
    })
    TargetEnum sourceToTarget(SourceEnum sourceEnum);
}

在这个例子中，如果源枚举值为 null，则目标枚举值为 TYPE_Z；如果源枚举值没有映射（即源枚举有其他值），则目标枚举值为 TYPE_X。

嵌套属性映射

MapStruct也支持嵌套属性的映射。例如，如果你的Car类有一个Engine属性，你可以这样定义你的Mapper：

@Mapper
public interface CarMapper {
    @Mapping(source = "engine.horsePower", target = "horsePower")
    CarDto carToCarDto(Car car);
}

在这个例子中，carToCarDto方法将Car的engine.horsePower属性映射到CarDto的horsePower属性。

反向映射

MapStruct还提供了反向映射的功能。你可以使用@InheritInverseConfiguration注解来创建反向的映射方法：

@Mapper
public interface CarMapper {
  
    CarDto carToCarDto(Car car);

    @InheritInverseConfiguration
    Car carDtoToCar(CarDto carDto);

}

在这个例子中，carDtoToCar方法是carToCarDto方法的反向映射。

使用装饰器增强Mapper

你可以使用装饰器来增强你的Mapper。

首先，定义一个装饰器类：

public abstract class CarMapperDecorator implements CarMapper {
  
    private final CarMapper delegate;
  
    public CarMapperDecorator(CarMapper delegate) {
        this.delegate = delegate;
    }

    @Override
    public CarDto carToCarDto(Car car) {
        CarDto dto = delegate.carToCarDto(car);
        dto.setMake(dto.getMake().toUpperCase());
        return dto;
    }

}

然后在你的Mapper接口中使用@DecoratedWith注解：

@Mapper
@DecoratedWith(CarMapperDecorator.class)
public interface CarMapper {
    CarDto carToCarDto(Car car);
}

使用@BeforeMapping和@AfterMapping进行预处理和后处理

你可以使用@BeforeMapping和@AfterMapping注解来进行映射前后的处理：

@Mapper
public abstract class CarMapper {
  
    @BeforeMapping
    protected void enrichCar(Car car) {
        car.setMake(car.getMake().toUpperCase());
    }

    @Mapping(source = "numberOfSeats", target = "seatCount")
    public abstract CarDto carToCarDto(Car car);
    
    @AfterMapping
    protected void enrichDto(Car car, @MappingTarget CarDto carDto) {
        carDto.setSeatCount(car.getNumberOfSeats());
    }

}

在这个例子中，enrichCar方法在映射前被调用，enrichDto方法在映射后被调用。

映射更新

MapStruct允许你将一个对象的属性更新到另一个已存在的对象。例如：

@Mapper
public interface CarMapper {
    @Mapping(source = "numberOfSeats", target = "seatCount")
    void updateCarFromDto(CarDto carDto, @MappingTarget Car car);
}

在这个例子中，updateCarFromDto方法将CarDto的属性更新到已存在的Car对象。

忽略某些字段

有时候，你可能想要忽略源对象中的某些字段。你可以使用@Mapping注解的ignore参数来实现这一点：

@Mapper
public interface CarMapper {
    @Mapping(target = "seatCount", ignore = true)
    CarDto carToCarDto(Car car);
}

在这个例子中，carToCarDto方法将忽略Car的seatCount字段。

常量映射

@Mapping注解constant属性可以用于将源对象的某个固定值映射到目标对象的属性：

@Mapper
public interface CarMapper {
    @Mapping(target = "carType", constant = "SEDAN")
    CarDto carToCarDto(Car car);
}

在这个例子中，carToCarDto方法将会把CarDto的carType字段设置为"SEDAN"，无论Car对象的实际内容如何。

使用@Mappings定义多个映射规则

你可以使用@Mappings注解来定义多个映射规则：

@Mapper
public interface CarMapper {
    @Mappings({
        @Mapping(source = "numberOfSeats", target = "seatCount"),
        @Mapping(source = "manufacturingDate", target = "year")
    })
    CarDto carToCarDto(Car car);
}

在这个例子中，carToCarDto方法将Car的numberOfSeats属性映射到CarDto的seatCount属性，将manufacturingDate属性映射到year属性。

默认值映射

MapStruct也支持默认值映射，你可以使用@Mapping注解的defaultValue参数来实现这一点：

@Mapper
public interface CarMapper {
    @Mapping(target = "seatCount", source = "numberOfSeats", defaultValue = "4")
    CarDto carToCarDto(Car car);
}