Краткое руководство по MapStruct

1. Обзор

В этом руководстве мы рассмотрим использование MapStruct , который, проще говоря, является картографом Java Bean.

Этот API содержит функции, которые автоматически сопоставляются между двумя компонентами Java Bean. С MapStruct нам нужно только создать интерфейс, и библиотека автоматически создаст конкретную реализацию во время компиляции.

2. MapStruct и передача шаблона объекта

В большинстве приложений вы заметите много стандартного кода, преобразующего POJO в другие POJO.

Например, общий тип преобразования происходит между сущностями, поддерживаемыми постоянством, и DTO, которые выходят на сторону клиента.

Итак, вот проблема, которую решает MapStruct: ручное создание модулей сопоставления компонентов требует много времени. Но библиотека может автоматически генерировать классы сопоставления компонентов.

3. Мавен

Давайте добавим следующую зависимость в наш Maven pom.xml :

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

Последний стабильный выпуск MapStruct и его процессор доступны в центральном репозитории Maven.

Давайте также добавим раздел annotationProcessorPaths в часть конфигурации плагина maven-compiler- plugin.

Обработчик mapstruct-processor используется для генерации реализации картографа во время сборки:

<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.4.2.Final</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

4. Базовое картографирование

4.1. Создание POJO

Давайте сначала создадим простой Java POJO:

public class SimpleSource {
    private String name;
    private String description;
    // getters and setters
}
 
public class SimpleDestination {
    private String name;
    private String description;
    // getters and setters
}

4.2. Интерфейс картографа

@Mapper
public interface SimpleSourceDestinationMapper {
    SimpleDestination sourceToDestination(SimpleSource source);
    SimpleSource destinationToSource(SimpleDestination destination);
}

Обратите внимание, что мы не создавали класс реализации для нашего SimpleSourceDestinationMapper, потому что MapStruct создает его за нас.

4.3. Новый картограф

Мы можем запустить обработку MapStruct, выполнив mvn clean install .

Это сгенерирует класс реализации в /target/generated-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. Прецедент

Наконец, со всем сгенерированным, давайте напишем тестовый пример, показывающий, что значения в SimpleSource соответствуют значениям в SimpleDestination :

public class SimpleSourceDestinationMapperIntegrationTest {
    private SimpleSourceDestinationMapper mapper
      = Mappers.getMapper(SimpleSourceDestinationMapper.class);
    @Test
    public void givenSourceToDestination_whenMaps_thenCorrect() {
        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 givenDestinationToSource_whenMaps_thenCorrect() {
        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. Сопоставление с внедрением зависимостей

Затем давайте получим экземпляр преобразователя в MapStruct, просто вызвав Mappers.getMapper(YourClass.class) .

Конечно, это очень ручной способ получения экземпляра. Тем не менее, гораздо лучшей альтернативой является внедрение картографа непосредственно туда, где он нам нужен (если в нашем проекте используется какое-либо решение для внедрения зависимостей).

К счастью, MapStruct имеет надежную поддержку как Spring, так и CDI ( контексты и внедрение зависимостей ).

Чтобы использовать Spring IoC в нашем картографе, нам нужно добавить атрибут componentModel в @Mapper со значением spring , а для CDI это будет cdi .

5.1. Изменить картограф

Добавьте следующий код в SimpleSourceDestinationMapper :

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

5.2. Внедрить компоненты Spring в Mapper

Иногда нам нужно использовать другие компоненты Spring внутри нашей логики сопоставления. В этом случае мы должны использовать абстрактный класс вместо интерфейса :

@Mapper(componentModel = "spring")
public abstract class SimpleDestinationMapperUsingInjectedService

Затем мы можем легко внедрить нужный компонент, используя известную аннотацию @Autowired, и использовать его в нашем коде:

@Mapper(componentModel = "spring")
public abstract class SimpleDestinationMapperUsingInjectedService {

    @Autowired
    protected SimpleService simpleService;

    @Mapping(target = "name", expression = "java(simpleService.enrichName(source.getName()))")
    public abstract SimpleDestination sourceToDestination(SimpleSource source);
}

Мы должны помнить, что не следует делать инжектируемый bean-компонент приватным! Это связано с тем, что MapStruct должен получить доступ к объекту в сгенерированном классе реализации.

6. Сопоставление полей с разными именами полей

В нашем предыдущем примере MapStruct смог автоматически сопоставить наши bean-компоненты, потому что они имеют одинаковые имена полей. Итак, что, если bean-компонент, который мы собираемся сопоставить, имеет другое имя поля?

В этом примере мы создадим новый компонент с именами Employee и EmployeeDTO .

6.1. Новые POJO

public class EmployeeDTO {
    private int employeeId;
    private String employeeName;
    // getters and setters
}

public class Employee {
    private int id;
    private String name;
    // getters and setters
}

6.2. Интерфейс картографа

При сопоставлении разных имен полей нам нужно будет настроить его исходное поле на целевое поле, и для этого нам нужно будет добавить аннотацию @Mappings . Эта аннотация принимает массив аннотаций @Mapping , которые мы будем использовать для добавления целевого и исходного атрибутов.

В MapStruct мы также можем использовать точечную нотацию для определения члена компонента:

@Mapper
public interface EmployeeMapper {
    @Mappings({
      @Mapping(target="employeeId", source="entity.id"),
      @Mapping(target="employeeName", source="entity.name")
    })
    EmployeeDTO employeeToEmployeeDTO(Employee entity);
    @Mappings({
      @Mapping(target="id", source="dto.employeeId"),
      @Mapping(target="name", source="dto.employeeName")
    })
    Employee employeeDTOtoEmployee(EmployeeDTO dto);
}

6.3. Прецедент

Опять же, нам нужно проверить, совпадают ли значения исходного и целевого объекта:

@Test
public void givenEmployeeDTOwithDiffNametoEmployee_whenMaps_thenCorrect() {
    EmployeeDTO dto = new EmployeeDTO();
    dto.setEmployeeId(1);
    dto.setEmployeeName("John");

    Employee entity = mapper.employeeDTOtoEmployee(dto);

    assertEquals(dto.getEmployeeId(), entity.getId());
    assertEquals(dto.getEmployeeName(), entity.getName());
}

Больше тестовых случаев можно найти в проекте GitHub .

7. Сопоставление бинов с дочерними бинами

Далее мы покажем, как сопоставить компонент со ссылками на другие компоненты.

7.1. Изменить POJO

Давайте добавим новую ссылку на bean-компонент к объекту Employee :

public class EmployeeDTO {
    private int employeeId;
    private String employeeName;
    private DivisionDTO division;
    // getters and setters omitted
}

public class Employee {
    private int id;
    private String name;
    private Division division;
    // getters and setters omitted
}

public class Division {
    private int id;
    private String name;
    // default constructor, getters and setters omitted
}

7.2. Изменить картограф

Здесь нам нужно добавить метод для преобразования Division в DivisionDTO и наоборот; если MapStruct обнаружит, что тип объекта необходимо преобразовать, а метод для преобразования существует в том же классе, он будет использовать его автоматически.

Давайте добавим это в маппер:

DivisionDTO divisionToDivisionDTO(Division entity);

Division divisionDTOtoDivision(DivisionDTO dto);

7.3. Изменить тестовый пример

Давайте изменим и добавим несколько тестовых случаев к существующему:

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

8. Сопоставление с преобразованием типов

MapStruct также предлагает несколько готовых неявных преобразований типов, и для нашего примера мы попытаемся преобразовать дату String в фактический объект Date .

Дополнительные сведения о неявном преобразовании типов см . в справочном руководстве по MapStruct .

8.1. Изменить бобы

Добавляем дату начала для нашего сотрудника:

public class Employee {
    // other fields
    private Date startDt;
    // getters and setters
}

public class EmployeeDTO {
    // other fields
    private String employeeStartDt;
    // getters and setters
}

8.2. Изменить картограф

Мы модифицируем маппер и предоставляем dateFormat для нашей даты начала:

@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 = "dd-MM-yyyy HH:mm:ss";
@Test
public void givenEmpStartDtMappingToEmpDTO_whenMaps_thenCorrect() throws ParseException {
    Employee entity = new Employee();
    entity.setStartDt(new Date());
    EmployeeDTO dto = mapper.employeeToEmployeeDTO(entity);
    SimpleDateFormat format = new SimpleDateFormat(DATE_FORMAT);
 
    assertEquals(format.parse(dto.getEmployeeStartDt()).toString(),
      entity.getStartDt().toString());
}
@Test
public void givenEmpDTOStartDtMappingToEmp_whenMaps_thenCorrect() throws ParseException {
    EmployeeDTO dto = new EmployeeDTO();
    dto.setEmployeeStartDt("01-04-2016 01:00:00");
    Employee entity = mapper.employeeDTOtoEmployee(dto);
    SimpleDateFormat format = new SimpleDateFormat(DATE_FORMAT);
 
    assertEquals(format.parse(dto.getEmployeeStartDt()).toString(),
      entity.getStartDt().toString());
}

9. Сопоставление с абстрактным классом

Иногда мы можем захотеть настроить наш преобразователь таким образом, чтобы он превышал возможности @Mapping.

Например, в дополнение к преобразованию типов мы можем каким-то образом преобразовать значения, как в нашем примере ниже.

В таких случаях мы можем создать абстрактный класс и реализовать методы, которые мы хотим настроить, и оставить абстрактными те, которые должны быть сгенерированы MapStruct.

9.1. Базовая модель

В этом примере мы будем использовать следующий класс:

public class Transaction {
    private Long id;
    private String uuid = UUID.randomUUID().toString();
    private BigDecimal total;

    //standard getters
}

и соответствующий DTO:

public class TransactionDTO {

    private String uuid;
    private Long totalInCents;

    // standard getters and setters
}

Сложная часть здесь заключается в преобразовании общей суммы BigDecimal в долларах в Long totalInCents .

9.2. Определение картографа

Мы можем добиться этого, создав наш Mapper как абстрактный класс:

@Mapper
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);
}

Здесь мы реализовали наш полностью настраиваемый метод сопоставления для преобразования одного объекта.

С другой стороны, мы оставили метод, предназначенный для сопоставления коллекции с абстрактным списком , поэтому MapStruct реализует его за нас.

9.3. Сгенерированный результат

Поскольку мы уже реализовали метод для сопоставления одной транзакции с TransactionDTO , мы ожидаем, что MapStruct будет использовать его во втором методе.

Будет сгенерировано следующее:

@Generated
class TransactionMapperImpl extends TransactionMapper {

    @Override
    public List<TransactionDTO> toTransactionDTO(Collection<Transaction> transactions) {
        if ( transactions == null ) {
            return null;
        }

        List<TransactionDTO> list = new ArrayList<>();
        for ( Transaction transaction : transactions ) {
            list.add( toTransactionDTO( transaction ) );
        }

        return list;
    }
}

Как видно из строки 12, MapStruct использует нашу реализацию в сгенерированном методе.

10. Аннотации до и после картирования

Вот еще один способ настроить возможности @Mapping с помощью аннотаций @BeforeMapping и @AfterMapping . Аннотации используются для обозначения методов, которые вызываются непосредственно перед и после логики сопоставления.

Они весьма полезны в сценариях, где мы можем захотеть, чтобы это поведение применялось ко всем сопоставленным супертипам.

Давайте рассмотрим пример, который сопоставляет подтипы Car ElectricCar и BioDieselCar с CarDTO .

При сопоставлении мы хотели бы сопоставить понятие типов с полем перечисления FuelType в DTO. Затем, после завершения сопоставления, мы хотели бы изменить имя DTO на верхний регистр.

10.1. Базовая модель

Мы будем использовать следующие классы:

public class Car {
    private int id;
    private String name;
}

Подтипы автомобилей :

public class BioDieselCar extends Car {
}

public class ElectricCar extends Car {
}

CarDTO с типом поля перечисления FuelType :

public class CarDTO {
    private int id;
    private String name;
    private FuelType fuelType;
}

public enum FuelType {
    ELECTRIC, BIO_DIESEL
}

10.2. Определение картографа

Теперь давайте продолжим и напишем наш абстрактный класс преобразователя, который сопоставляет Car с CarDTO :

@Mapper
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 — это аннотация параметра, которая заполняет DTO целевого сопоставления непосредственно перед выполнением логики сопоставления в случае @BeforeMapping и сразу после в случае `` аннотированного метода @AfterMapping .

10.3. Результат

Определенный выше CarsMapper генерирует реализацию : ****

@Generated
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. Поддержка Ломбока

В последней версии MapStruct была объявлена поддержка Lombok. Таким образом, мы можем легко сопоставить исходный объект и пункт назначения с помощью Lombok.

Чтобы включить поддержку Lombok, нам нужно добавить зависимость в пути процессора аннотаций. Начиная с версии Lombok 1.18.16, мы также должны добавить зависимость от lombok-mapstruct-binding . Теперь у нас есть mapstruct-processor, а также Lombok в плагине компилятора Maven:

<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.4.2.Final</version>
            </path>
            <path>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
            <version>1.18.4</version>
            </path>
            <path>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok-mapstruct-binding</artifactId>
            <version>0.2.0</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

Давайте определим исходный объект, используя аннотации Lombok:

@Getter
@Setter
public class Car {
    private int id;
    private String name;
}

И целевой объект передачи данных:

@Getter
@Setter
public class CarDTO {
    private int id;
    private String name;
}

Интерфейс картографа для этого остается таким же, как в нашем предыдущем примере:

@Mapper
public interface CarMapper {
    CarMapper INSTANCE = Mappers.getMapper(CarMapper.class);
    CarDTO carToCarDTO(Car car);
}

12. Поддержка выражения по умолчанию

Начиная с версии 1.3.0, мы можем использовать атрибут defaultExpression аннотации @Mapping , чтобы указать выражение, определяющее значение поля назначения, если исходное поле имеет значение null . Это в дополнение к существующей функциональности атрибута defaultValue .

Исходный объект:

public class Person {
    private int id;
    private String name;
}

Объект передачи данных назначения:

public class PersonDTO {
    private int id;
    private String name;
}

Если поле id исходного объекта равно null , мы хотим сгенерировать случайный идентификатор и назначить его получателю, сохраняя другие значения свойств как есть:

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

Давайте добавим тестовый пример для проверки выполнения выражения:

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

13. Заключение

В этой статье представлено введение в MapStruct. Мы представили большую часть основ библиотеки сопоставления и способы ее использования в наших приложениях.

Реализацию этих примеров и тестов можно найти в проекте GitHub . Это проект Maven, поэтому его должно быть легко импортировать и запускать как есть.