Mapstruct

Mapstruct — это библиотека для Java, которая генерирует код для передачи данных между разными сущностями в программе. Она помогает сопоставлять объекты из одной сущности с другой. Этот процесс называется маппингом данных, а инструмент для передачи — маппером, или Java mapper.

Маппер в широком смысле — подсистема для преобразования и передачи данных. В случае с Mapstruct разработчик обычно пишет аннотацию маппера — короткий блок кода. Он описывает, какую информацию и в какую сущность нужно передать. А библиотека на основе этой аннотации генерирует код, который и занимается непосредственной передачей данных. Поэтому Mapstruct часто называют генератором кода, который базируется на аннотациях.

Благодаря Mapstruct маппинг можно автоматизировать: не понадобится вручную писать методы, которые обрабатывают данные и передают их в другую сущность, в другой слой программы. Такие методы — большое количество лишнего кода, который надо писать и поддерживать. Mapstruct избавляет от этой проблемы.

Кто и зачем пользуется Mapstruct

Библиотеку используют разработчики, чтобы упростить и ускорить написание кода. Для маппинга есть и другие методы, но конкретно Mapstruct имеет ряд преимуществ: он автоматизирован и потому не отнимает лишнего времени, типобезопасен, быстро работает.

Mapstruct позволяет:

• упростить работу программистов, позволить им сконцентрироваться на бизнес-логике;
• сократить время на написание кода;
• избавиться от ошибок, связанных с человеческим фактором;
• убрать необходимость поддерживать большое количество шаблонного кода мапперов;
• ускорить работу самой программы, так как Mapstruct работает быстро и генерирует код прямо во время компиляции;
• увеличить производительность — по этой же причине.

Приложения на Java обычно масштабные и многоуровневые, а передача данных между уровнями нужна часто. Использовать для нее Mapstruct удобнее, чем писать нужные методы вручную.

Как работает Mapstruct

По определению с официального сайта Mapstruct — процессор аннотаций, который подключается к компилятору языка Java. Его можно добавить к проекту в любой популярной среде для языка, он совместим с фреймворками для автоматизированной сборки Java-кода, такими как Maven или Gradle.

Во время компиляции кода, то есть его преобразования в исполняемый файл для системы, Mapstruct «читает» написанные разработчиком аннотации. Это блоки описательного кода: он ничего не делает, но описывает, что и куда надо передать. На их основе Mapstruct создает непосредственную реализацию этих описаний и запускает ее. Это работает только с аннотациями для мапперов: именно для них нужна библиотека.

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

Как пользоваться Mapstruct

Подключение к проекту. Мы не будем приводить точные инструкции: они различаются для разных сред и фреймворков. Если вы работаете с Maven, достаточно добавить одну зависимость в файл .pom — это специальный файл, которым фреймворк пользуется для подключения сторонних модулей. Затем понадобится добавить плагин для Mapstruct в раздел <build>: эта часть файла описывает сборку.

В случае с другими инструментами порядок действий примерно такой же: различаются в основном форматы записи и синтаксис. Подробнее о подключении к разным фреймворкам можно почитать на официальном сайте проекта: там даны инструкции для всех популярных инструментов.

Написание аннотации. Инструкция для Mapstruct озаглавливается аннотацией @Mapper; на следующей строке после этого указания разработчик начинает писать интерфейс. По структуре интерфейс похож на класс, но в Java между этими понятиями есть различие: у интерфейса есть только методы, то есть действия, он не хранит никаких свойств.

Описание интерфейса начинается со слов public interface <name>, причем имя может быть любым, но рекомендуется называть сущности понятными именами.

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

<имя сущности, в которую переносим данные> <название метода> (<исходный объект с данными>);

Методом называют функцию внутри интерфейса или объекта. Название метода придумывает сам разработчик; рекомендуется делать его понятным и наглядным. Сам код для метода в этом случае писать не нужно: это та самая практическая реализация, которую должен сгенерировать Mapstruct.

Дополнительные объяснения. Разработчик также может дать Mapstruct дополнительные инструкции с объяснениями, как преобразовывать объекты, если их типы или имена полей не совпадают: в изначальной сущности одно, а в целевой должно быть другое. Это делается с помощью аннотации @Mapping внутри интерфейса: после нее в скобочках указываются изначальные и целевые имена.

Выглядит это так:

@Mapping (source = <исходное имя>, target = <нужное имя>);

По похожему принципу можно преобразовать типы.

Получение реализации. Этот шаг не всегда обязателен. Но если вы хотите получить созданный Mapstruct код, записать его куда-то и использовать позже — так можно сделать. В интерфейсе можно объявить переменную INSTANCE и записать туда сгенерированный маппер с помощью специального метода getMapper.

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

Компиляция. Скомпилировать проект, в котором используется Mapstruct, понадобится вручную. Для этого в большинстве фреймворков для автоматизации достаточно набрать одну команду в консоли: она запустит компилятор.

После компиляции в папке проекта появятся новые файлы. Один из них — реализация маппера, обычно он располагается в подпапке с классами. Среды разработки для Java позволяют декомпилировать файлы, то есть преобразовать из исполняемых инструкций для системы обратно в исходный код: можно воспользоваться этой возможностью и посмотреть, что сгенерировал Mapstruct.

Тестирование. Чтобы убедиться, что сгенерированный код работает правильно, для него рекомендуют писать unit-тесты: так называются тесты, которые охватывают только один конечный компонент. Это перестраховка: она помогает убедиться, что всё перенеслось правильно. Тесты особенно важны на ранних этапах использования, например при обучении.

Как начать пользоваться Mapstruct

Скачать библиотеку можно с официального репозитория проекта на GitHub. Она бесплатная, с открытым исходным кодом, так что вы сможете просмотреть его в любой момент. Потом останется подключить Mapstruct к проекту — мы уже писали про это выше. Можно просто воспользоваться инструкцией с официального сайта. После этого библиотекой можно пользоваться.