Как подключить MapStruct к проекту MapStruct — это code-gener | Java библиотека

Как подключить MapStruct к проекту

MapStruct — это code-generation библиотека для автоматического маппинга между Java-объектами.

Работает на этапе компиляции, генерирует чистый код без рефлексии — в разы быстрее ModelMapper и Dozer.

Добавляем зависимости

Нужно добавить две зависимости: саму библиотеку mapstruct и процессор mapstruct-processor. Процессор отвечает за генерацию кода во время компиляции.

Критически важно правильно настроить maven-compiler-plugin, именно он запускает annotation processors. В секции annotationProcessorPaths прописываем mapstruct-processor, а если используете Lombok, добавляем его тоже плюс специальный binding для их совместной работы.

Создаём Mapper интерфейс

Создаёте обычный Java-интерфейс с аннотацией @Mapper(componentModel = "spring"). Параметр componentModel указывает, что MapStruct должен сгенерировать Spring-бин, который можно инжектить через конструктор.

В интерфейсе объявляете методы-конвертеры: например UserDto toDto(User user) или List toDtoList(List users). MapStruct сам поймёт, какие поля во что маппить, если названия совпадают.

Настраиваем кастомный маппинг

Когда названия полей отличаются или нужна дополнительная логика, используйте аннотацию @Mapping:

source/target — для переименования полей: @Mapping(target = "fullName", source = "firstName")
expression — для Java-выражений: можно написать простую логику прямо в аннотации
ignore — чтобы игнорировать поле: @Mapping(target = "password", ignore = true)
dateFormat — для форматирования дат: автоматическая конвертация LocalDateTime в String
qualifiedByName — для вызова кастомных методов-конвертеров

Работа со вложенными объектами

MapStruct умеет автоматически маппить вложенные структуры. Если у вас в User есть поле Address, а в UserDto есть AddressDto — создайте отдельный AddressMapper и укажите его в параметре uses = {AddressMapper.class}.

MapStruct сам найдёт нужный маппер и применит его для вложенных объектов. Это работает рекурсивно для любой глубины вложенности.

Обновление существующих объектов

Часто нужно не создавать новый объект, а обновить существующий. Для этого используйте аннотацию @MappingTarget на втором параметре метода. MapStruct сгенерирует код, который обновит только нужные поля.

Добавьте @BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE) — тогда null-значения из DTO не затрут существующие данные в Entity.

Кастомные конвертеры

Для сложной логики добавьте в интерфейс default-методы. Пометьте их @Named("имя") и ссылайтесь через qualifiedByName. Например, для конвертации enum в русский текст или склейки нескольких полей.

Можно также создать отдельный класс с @Component и helper-методами, затем подключить его через параметр uses.

Что происходит под капотом

MapStruct анализирует ваш интерфейс на этапе компиляции, смотрит на типы полей, их названия и аннотации. Затем генерирует простой Java-код с прямым присвоением значений, никакой магии, рефлексии или proxy.

Сгенерированный код можно открыть и прочитать. Он выглядит так, будто вы написали его вручную. Это упрощает отладку и понимание происходящего.

Подписывайся на наш канал в Max