MapStruct快速指南

电玩女神 2023-01-15 02:11 195阅读 0赞

# 1.介绍 #

探讨MapStruct的使用，简而言之就是Java Bean映射器。

该API包含可在两个Java Bean之间自动映射的功能。 使用MapStruct，我们只需要创建接口，该库将在编译时自动创建具体的实现。

# 2.MapStruct和传输对象模式 #

对于大多数应用程序，会有很多将POJO转换为其他POJO的代码。

例如，在DO的实体和发往客户端的DTO之间会发生一种常见的转换类型。

这就是MapStruct解决的问题：手动创建bean映射器非常耗时。 但是该库可以自动生成bean映射器类。

# 3. Maven #

增加maven依赖

<dependency>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct</artifactId>
        <version>1.3.1.Final</version> 
    </dependency>

# 4.基本映射 #

## 4.1. 创建一个POJO ##

首先创建一个简单的Java POJO：

@Data
    public class SimpleSource { 
        private String name;
        private String description;
    }

@Data
    public class SimpleDestination { 
        private String name;
        private String description;
    }

## 4.2. Mapper接口 ##

@Mapper(componentModel = "spring")
    public interface SimpleSourceDestinationMapper { 
        /** * SimpleSource对象 转 SimpleDestination * * @param source source * @return SimpleDestination */
        SimpleDestination sourceToDestination(SimpleSource source);
    
        /** * SimpleDestination 对象转 SimpleSource * * @param destination destination * @return SimpleSource */
        SimpleSource destinationToSource(SimpleDestination destination);
    }

注意，没有为SimpleSourceDestinationMapper创建实现类，因为MapStruct为自动创建了。

## 4.3创建Mapper实现类 ##

可以通过执行mvn全新安装来触发MapStruct处理。

这将在/target/generate-sources/annotations/下生成实现类。

这是MapStruct为自动创建的类：

public class SimpleSourceDestinationMapperImpl
      implements SimpleSourceDestinationMapper { 
        @Override
        public SimpleDestination sourceToDestination(SimpleSource source) { 
            if ( source == null ) { 
                return null;
            }
            SimpleDestination simpleDestination = new SimpleDestination();
            simpleDestination.setName( source.getName() );
            simpleDestination.setDescription( source.getDescription() );
            return simpleDestination;
        }
        @Override
        public SimpleSource destinationToSource(SimpleDestination destination){ 
            if ( destination == null ) { 
                return null;
            }
            SimpleSource simpleSource = new SimpleSource();
            simpleSource.setName( destination.getName() );
            simpleSource.setDescription( destination.getDescription() );
            return simpleSource;
        }
    }

## 4.4测试 ##

@RunWith(SpringRunner.class)
    @SpringBootTest
    public class MapStructTest { 
        @Autowired
        private SimpleSourceDestinationMapper mapper;
        @Test
        public void test1() { 
            SimpleSource simpleSource = new SimpleSource();
            simpleSource.setName("SourceName");
            simpleSource.setDescription("SourceDescription");
            SimpleDestination destination = mapper.sourceToDestination(simpleSource);
    
            assertEquals(simpleSource.getName(), destination.getName());
            assertEquals(simpleSource.getDescription(),
                    destination.getDescription());
        }
    
        @Test
        public void test2() { 
            SimpleDestination destination = new SimpleDestination();
            destination.setName("DestinationName");
            destination.setDescription("DestinationDescription");
            SimpleSource source = mapper.destinationToSource(destination);
            assertEquals(destination.getName(), source.getName());
            assertEquals(destination.getDescription(),
                    source.getDescription());
        }
    }

# 5.依赖注入映射 #

调用Mappers.getMapper(YourClass.class)在MapStruct中获得一个映射器的实例。

当然，这是获取实例是手动的方法。，更好的选择是将映射器直接注入到我们需要的位置（如果我们的项目使用任何依赖注入解决方案）。

MapStruct对Spring和CDI（上下文和依赖注入）都提供了可靠的支持。

要在我们的映射器中使用Spring IoC，需要设置componentModel属性添加到@Mapper

>     /**
>      * Specifies the component model to which the generated mapper should
>      * adhere. Supported values are
>      * <ul>
>      * <li> {@code default}: the mapper uses no component model, instances are
>      * typically retrieved via {@link Mappers#getMapper(Class)}</li>
>      * <li>
>      * {@code cdi}: the generated mapper is an application-scoped CDI bean and
>      * can be retrieved via {@code @Inject}</li>
>      * <li>
>      * {@code spring}: the generated mapper is a Spring bean and
>      * can be retrieved via {@code @Autowired}</li>
>      * <li>
>      * {@code jsr330}: the generated mapper is annotated with {@code @javax.inject.Named} and
>      * {@code @Singleton}, and can be retrieved via {@code @Inject}</li>
>      * </ul>
>      * The method overrides an unmappedTargetPolicy set in a central configuration set
>      * by {@link #config() }
>      *
>      * @return The component model for the generated mapper.
>      */
>     String componentModel() default "default";

## 5.1 修改映射器 ##

将以下代码添加到SimpleSourceDestinationMapper：

@Mapper(componentModel = "spring")
    public interface SimpleSourceDestinationMapper

## 6.映射具有不同字段名称的字段 ##

在前面的示例中，MapStruct能够自动映射bean，因为它们具有相同的字段名称。 那么，如果要映射的bean具有不同的字段名称怎么办？

在下面的示例中，创建一个名为Employee和EmployeeDTO的新bean。

## 6.1新建POJO ##

@Data
    public class EmployeeDTO { 
        private int employeeId;
        private String employeeName;
    }

@Data
    public class Employee { 
        private int id;
        private String name;
    }

## 6.2映射接口 ##

当映射不同的字段名称时，需要将其源字段配置为目标字段，并且为此，需要添加@Mappings注解。 该注解接受@Mapping注解的数组，将使用该数组添加target和source属性。

在MapStruct中，还可以使用点表示法来定义bean的成员

@Mapper(componentModel = "spring")
    public interface EmployeeMapper { 
        /** * Employee 转 EmployeeDTO * * @param entity entity * @return EmployeeDTO */
        @Mappings(value = { 
                @Mapping(target = "employeeId", source = "entity.id"),
                @Mapping(target = "employeeName", source = "entity.name")
        })
        EmployeeDTO employeeToEmployeeDTO(Employee entity);
    
        /** * EmployeeDTO 转 Employee * * @param dto dto * @return Employee */
        @Mappings({ 
                @Mapping(target = "id", source = "dto.employeeId"),
                @Mapping(target = "name", source = "dto.employeeName")
        })
        Employee employeeDTOtoEmployee(EmployeeDTO dto);
    }

测试

@Test
        public void test3() { 
            EmployeeDTO dto = new EmployeeDTO();
            dto.setEmployeeId(1);
            dto.setEmployeeName("张三");
    
            Employee entity = employeeMapper.employeeDTOtoEmployee(dto);
    
            assertEquals(dto.getEmployeeId(), entity.getId());
            assertEquals(dto.getEmployeeName(), entity.getName());
        }

# 7.映射bean和子bean #

## 7.1.修改POJO ##

@Data
    @AllArgsConstructor
    @NoArgsConstructor
    public class Division { 
        private int id;
        private String name;
    }

@Data
    @AllArgsConstructor
    @NoArgsConstructor
    public class DivisionDTO { 
        private int id;
        private String name;
    }

@Data
    public class Employee { 
        private int id;
        private String name;
        private Division division;
    }

@Data
    public class EmployeeDTO {
        private int employeeId;
        private String employeeName;
        private DivisionDTO division;
    }

## 7.2修改映射 ##

在这里，需要添加一种将Division转换为DivisionDTO的方法； 如果MapStruct检测到需要转换的对象类型并且转换的方法存在于同一类中，它将自动使用它。

将其添加到映射器中：

/**
         * Division 转  DivisionDTO
         *
         * @param entity entity
         * @return DivisionDTO
         */
        DivisionDTO divisionToDivisionDTO(Division entity);
    
        /**
         * DivisionDTO转  Division
         *
         * @param dto dto
         * @return Division
         */
        Division divisionDTOtoDivision(DivisionDTO dto);

测试

@Test
        public void test4() { 
            EmployeeDTO dto = new EmployeeDTO();
            dto.setDivision(new DivisionDTO(1, "Division1"));
            Employee entity = employeeMapper.employeeDTOtoEmployee(dto);
            assertEquals(dto.getDivision().getId(), entity.getDivision().getId());
            assertEquals(dto.getDivision().getName(), entity.getDivision().getName());
        }

# 8.类型转换映射 #

MapStruct还提供了一些现成的隐式类型转换，对于下面的示例，将String date转换为实际的Date对象。

## 8.1修改Beans ##

public class Employee { 
        // add field
        private Date startDt;
    }

public class EmployeeDTO { 
        // add field
        private String employeeStartDt;
    }

## 8.2修改Mapper ##

修改映射器，提供日期转化格式：

@Mappings({ 
      @Mapping(target="employeeId", source = "entity.id"),
      @Mapping(target="employeeName", source = "entity.name"),
      @Mapping(target="employeeStartDt", source = "entity.startDt",
               dateFormat = "dd-MM-yyyy HH:mm:ss")})
    EmployeeDTO employeeToEmployeeDTO(Employee entity);
    @Mappings({ 
      @Mapping(target="id", source="dto.employeeId"),
      @Mapping(target="name", source="dto.employeeName"),
      @Mapping(target="startDt", source="dto.employeeStartDt",
               dateFormat="dd-MM-yyyy HH:mm:ss")})
    Employee employeeDTOtoEmployee(EmployeeDTO dto);

## 8.3单元测试 ##

private static final String DATE_FORMAT = "yyyy-MM-dd HH:mm:ss";
    
    
    @Test
    public void test5() throws ParseException { 
        Employee entity = new Employee();
        entity.setStartDt(new Date());
        EmployeeDTO dto = employeeMapper.employeeToEmployeeDTO(entity);
        SimpleDateFormat format = new SimpleDateFormat(DATE_FORMAT);
    
        assertEquals(format.parse(dto.getEmployeeStartDt()).toString(),
                     entity.getStartDt().toString());
    }
    @Test
    public void test6() throws ParseException { 
        EmployeeDTO dto = new EmployeeDTO();
        dto.setEmployeeStartDt("2021-04-19 01:00:00");
        Employee entity = employeeMapper.employeeDTOtoEmployee(dto);
        SimpleDateFormat format = new SimpleDateFormat(DATE_FORMAT);
    
        assertEquals(format.parse(dto.getEmployeeStartDt()).toString(),
                     entity.getStartDt().toString());
    }

# 9.使用抽象类进行映射 #

有时，可能想以超出@Mapping功能的方式自定义映射器。

例如，除了类型转换外，可能还希望以某种方式转换值，如下面的示例所示。

在这种情况下，可以创建一个抽象类并实现要定制的方法，而将那些应该由MapStruct生成的方法保留为抽象。

## 9.1 基本Model ##

@Data
    @AllArgsConstructor
    @NoArgsConstructor
    public class Transaction { 
        private Long id;
        private String uuid = UUID.randomUUID().toString();
        private BigDecimal total;
    }

@Data
    @AllArgsConstructor
    @NoArgsConstructor
    public class TransactionDTO { 
    
        private String uuid;
        private Long totalInCents;
    }

这里问题是将BigDecimal的总金额转换为Long的totalInCents。

## 9.2定义映射器 ##

可以通过将Mapper创建为抽象类：

@Mapper(componentModel = "spring")
    public abstract class TransactionMapper { 
        public TransactionDTO toTransactionDTO(Transaction transaction) { 
            TransactionDTO transactionDTO = new TransactionDTO();
            transactionDTO.setUuid(transaction.getUuid());
            transactionDTO.setTotalInCents(transaction.getTotal()
                    .multiply(new BigDecimal("100")).longValue());
            return transactionDTO;
        }
    
        public abstract List<TransactionDTO> toTransactionDTO(
                Collection<Transaction> transactions);
    }

上面代码为单个对象转换实现了完全自定义的映射方法。

另一方面，保留了该方法，该方法用于将Collection映射到List抽象，因此MapStruct将实现它。

## 9.3生成结果 ##

由于已经实现了将单个Transaction映射到TransactionDTO的方法，因此MapStruct在第二种方法中使用它。

MapStruct生成的代码如下：

public class TransactionMapperImpl extends TransactionMapper { 
    
        @Override
        public List<TransactionDTO> toTransactionDTO(Collection<Transaction> transactions) { 
            if ( transactions == null ) { 
                return null;
            }
    
            List<TransactionDTO> list = new ArrayList<TransactionDTO>( transactions.size() );
            for ( Transaction transaction : transactions ) { 
                list.add( toTransactionDTO( transaction ) );
            }
    
            return list;
        }
    }

## 9.4单元测试 ##

@Test
        public void test7()  { 
            Transaction transaction1 = new Transaction();
            transaction1.setTotal(new BigDecimal("10.0"));
    
            Transaction transaction2 = new Transaction();
            transaction2.setTotal(new BigDecimal("20.0"));
            List<Transaction> arrayList = new ArrayList<>();
            arrayList.add(transaction1);
            arrayList.add(transaction2);
            List<TransactionDTO> dtos = transactionMapper.toTransactionDTO(arrayList);
            assertEquals(dtos.size(),2);
            System.out.println(dtos);
        }

# 10.映射前和映射后注解 #

这是使用@BeforeMapping和@AfterMapping注解来自定义@Mapping功能的另一种方法。 注解用于标记在映射逻辑之前和之后立即调用的方法。

此行为应用于所有映射超类型的情况下非常有用。

下面示例CarElectricCar和BioDieselCar的子类型映射到CarDTO的示例。

在映射时，将类型的概念映射到DTO中的FuelType枚举字段。 然后，完成映射后，将DTO的名称更改为大写。

## 10.1基本Model ##

使用以下类：

@Data
    @AllArgsConstructor
    @NoArgsConstructor
    public class Car { 
        private int id;
        private String name;
    }

Car的子类

public class BioDieselCar extends Car { 
    }

public class ElectricCar extends Car { 
    }

CarDTO增加一个枚举类型

@Data
    @AllArgsConstructor
    @NoArgsConstructor
    public class CarDTO {
        private int id;
        private String name;
        private FuelType fuelType;
    }

public enum FuelType {
        ELECTRIC, BIO_DIESEL
    }

## 10.2定义映射器 ##

@Mapper(componentModel = "spring")
    public abstract class CarsMapper { 
        @BeforeMapping
        protected void enrichDTOWithFuelType(Car car, @MappingTarget CarDTO carDto) { 
            if (car instanceof ElectricCar) { 
                carDto.setFuelType(FuelType.ELECTRIC);
            }
            if (car instanceof BioDieselCar) { 
                carDto.setFuelType(FuelType.BIO_DIESEL);
            }
        }
    
        @AfterMapping
        protected void convertNameToUpperCase(@MappingTarget CarDTO carDto) { 
            carDto.setName(carDto.getName().toUpperCase());
        }
    
        public abstract CarDTO toCarDto(Car car);
    }

@MappingTarget是一个参数注解，在@BeforeMapping情况下，在执行映射逻辑之前，而在@AfterMapping注解方法的情况下，则在参数映射之后填充目标映射DTO。

## 10.3结果 ##

上面定义的CarsMapper生成实现：

public class CarsMapperImpl extends CarsMapper { 
    
        @Override
        public CarDTO toCarDto(Car car) { 
            if (car == null) { 
                return null;
            }
    
            CarDTO carDTO = new CarDTO();
            enrichDTOWithFuelType(car, carDTO);
            carDTO.setId(car.getId());
            carDTO.setName(car.getName());
            convertNameToUpperCase(carDTO);
            return carDTO;
        }
    }

# 11.对Lombok的支持 #

在最新版本的MapStruct中，宣布了对Lombok的支持。 因此，可以使用Lombok轻松映射源实体和目的地。

要启用Lombok支持，需要在注解处理器路径中添加依赖项。 现在Maven编译器插件中有了mapstruct-processor和Lombok：

<plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.5.1</version>
        <configuration>
            <source>1.8</source>
            <target>1.8</target>
            <annotationProcessorPaths>
                <path>
                    <groupId>org.mapstruct</groupId>
                    <artifactId>mapstruct-processor</artifactId>
                    <version>1.3.1.Final</version>
                </path>
                <path>
                    <groupId>org.projectlombok</groupId>
                    <artifactId>lombok</artifactId>
    	        <version>1.18.4</version>
                </path>
            </annotationProcessorPaths>
        </configuration>
    </plugin>

# 12.支持defaultExpression #

从版本1.3.0开始，可以使用@Mapping注解的defaultExpression属性来指定一个表达式，如果源字段为null，则该表达式将确定目标字段的值。 这是对现有defaultValue属性功能的补充。

源实体

@Data
    @AllArgsConstructor
    @NoArgsConstructor
    public class Person { 
        private String id;
        private String name;
    }

目标实体

@Data
    @AllArgsConstructor
    @NoArgsConstructor
    public class PersonDTO { 
        private String id;
        private String name;
    }

如果源实体的id字段为null,生成一个随机id并将其分配给目标，并保持其他属性值保持不变：

@Mapper(componentModel = "spring")
    public interface PersonMapper { 
        @Mapping(target = "id", source = "person.id",
                defaultExpression = "java(java.util.UUID.randomUUID().toString())")
        PersonDTO personToPersonDTO(Person person);
    }

生成的实现类如下：

@Component
    public class PersonMapperImpl implements PersonMapper { 
    
        @Override
        public PersonDTO personToPersonDTO(Person person) { 
            if ( person == null ) { 
                return null;
            }
    
            PersonDTO personDTO = new PersonDTO();
    
            if ( person.getId() != null ) { 
                personDTO.setId( person.getId() );
            }
            else { 
                personDTO.setId( java.util.UUID.randomUUID().toString() );
            }
            personDTO.setName( person.getName() );
    
            return personDTO;
        }
    }

单元测试

@Test
        public void test8() { 
            Person entity = new Person();
            entity.setName("Micheal");
            PersonDTO personDto = personMapper.personToPersonDTO(entity);
            assertNull(entity.getId());
            assertNotNull(personDto.getId());
            assertEquals(personDto.getName(), entity.getName());
        }

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25pdWdhbmcwOTIw_size_16_color_FFFFFF_t_70]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25pdWdhbmcwOTIw_size_16_color_FFFFFF_t_70]: /images/20221022/f63ec7c8584540338af3d8c09f1fdb69.png