Приветствую всех читателей публикации! Я являюсь автором телеграмм канала "Заметки джависта". Сегодня хочу поделиться своим опытом работы с MapStruct, проложив основу и базовые принципы для начала работы с библиотекой.
Исходный код проекта: github
В этой статье мы разберемся с такими понятиями как DTO, Mapping, а также примерами их использования (в самом конце вы увидите полезные ссылки на доп источники по теме).
Я потратил на изучение данной библиотеки немало нервных клеток, и уверен, что узнал далеко не все способы и лайфхаки, но постарался донести информацию с практической стороны, чтобы вы с самого старта не испытывали "нежданчиков" и сэкономили свое время в попытках найти работающий способ.
Скрытый текст
СПОЙЛЕР: в данном проекте я не использую слой service, а обращаюсь к repository напрямую, и также максимально упростил реализацию, чтобы сфокусироваться на рассматриваемой теме.
Начальные данные
Смоделируем ситуацию: у нас есть некий сервис, который работает с пользователями. Сохраняет, обновляет и возвращает данные о пользователях. Стандартный набор полей сущности User выглядит так: id, username, email, password.
Когда пользователь регистрируется в нашей системе, мы сохраняем переданные данные в БД (базу данных), и затем возвращаем сохраненные данные, а также статус, в зависимости от результата операции (успех или ошибку).
Вопрос: как вы считаете, стоит ли включать в ответ клиенту поле password при успешном сохранении пользователя?
Скрытый текст
Спойлер: нет!
Конечно, можно обнулить поле password, и передать его клиенту - но мы можем забыть выполнить обнуление пароля, и передать его в ответе - а там на стороне клиента данные могут спокойно перехватить и использовать в своих целях (помните, что клиент это не только браузер - могут быть другие приложения, которые используют наш API).
Именно поэтому мы создадим дополнительный объект UserResponse, который и является DTO, и будет иметь только те поля, которые должен получить клиент, исключая поле password, как показано на рисунке ниже:
Мы, как разработчики, должны заботиться о безопасности на своей стороне. Если есть возможность и необходимость скрыть некоторые поля, которые как пример не нужны, либо представляют особую важность (в данном случае поле password - пароль пользователя), то лучше не включать их в конечный ответ клиенту (клиентом может быть наш микросервис, либо браузер, либо любой другой сервис, который обращается к нашему серверу)
Для понимания: клиент-серверная архитектура предполагает, что любой, кто обращается к серверу, является клиентом. А тот, кто принимает те самые запросы и обрабатывает их, является сервером. То есть клиентом и сервером могут быть сервисы, которые взаимодействуют между собой, даже в рамках одной структуры.
Таким образом мы видим, что DTO (Data transfer object) - объект передачи данных, смысл которого заключается в хранении промежуточных данных. Когда мы возвращаем данные клиенту, обычно передаем DTO обьект (если того требует логика), это как раз все данные (в нашем случае id, username, email).
По сути, DTO - это обычный Java объект, который не является частью бизнес модели (тогда как наш User - представление реального пользователя с набором данных), но служит неким хранилищем для данных, которые надо передать (отсюда и название - объект передачи данных).
Mapping: что ты, черт возьми, такое?
Теперь мы двигаемся к следующему вопросу: как нам собственно привести объект User к объекту UserResponse?
На этом этапе в игру вступает понятие маппинг (eng: mapping), которое подразумевает процесс преобразования объекта X в объект Y, в нашем случае это преобразование User ---> UserResponse.
Простыми словами: маппинг нужен чтобы преобразовывать одни объекты и поля к другим объектам.
MapStruct: смаппь меня, если сможешь
MapStruct - это библиотека, которая по сути и является маппером. Мапперов бывает много, но самый распространенный и удобный - MapStruct.
С помощью маппера нам не придется делать преобразование объектов руками (создавать новый объект, класть туда нужные поля, и возвращать наш DTO), все делается автоматически, ну или почти..
Зачем нам вообще нужен маппер, к чему лишние технологии?
Скрытый текст
Хороший вопрос. В процессе работы над реальными задачами, вам понадобится добавлять дополнительную логику (устанавливать значения по умолчанию, как пример текущее время, или другие константы / enum-значения, преобразовывать данные (шифровать пароль, генерировать никнейм), и т.п).
Проще использовать уже готовую библиотеку, которая сэкономит ваше время, нервы, и позволит реализовывать более гибкое поведение для конкретных ситуаций.
Теория - хорошо, а практика - еще лучше!
Для начала нам надо выбрать систему сборки для проекта (в данном примере я использую Gradle, но пример подключения библиотеки для Maven будет также приведен ниже).
dependencies {
//...
// MapStruct
implementation 'org.mapstruct:mapstruct:1.5.5.Final'
annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.5.Final'
}<properties>
<org.mapstruct.version>1.5.5.Final</org.mapstruct.version>
</properties>
...
<dependencies>
<dependency>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct</artifactId>
<version>${org.mapstruct.version}</version>
</dependency>
</dependencies>
...
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
<annotationProcessorPaths>
<path>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-processor</artifactId>
<version>${org.mapstruct.version}</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
</plugins>
</build>Создадим сущность User:
@Data
@Entity
@NoArgsConstructor
@AllArgsConstructor
@Table(name = "users")
public class User {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
private String username;
private String email;
private String password;
}А также UserResponse (dto) для ответа клиенту:
public record UserResponse(
Long id,
String username,
String email) {
}Не пугайтесь, если увидели record впервые: это встроенное ключевое слово в Java, которое позволяет создать неизменяемый класс с final полями (мы не можем изменить поля после создания объекта), а также автоматически сгенерированными hashcode()&equals() + toString() + get() методами.
UserMapper - наш первый маппер
Теперь создадим interface UserMapper, который как раз таки и будет содержать основную логику конвертации (маппинга) сущности в DTO:
@Mapper(componentModel = MappingConstants.ComponentModel.SPRING)
public interface UserMapper {
UserResponse toUserResponse(User user); //map User to UserResponse
List<UserResponse> toUserResponseList(List<User> users); //map list of User to list of UserResponse
}Как видно, ничего сложного:
Объявляем интерфейс (или абстрактный класс) с именем 'Mapper' в конце (это скорее правило хорошего тона, но не является обязательным условием), а также помещаем в папку mapper (чтобы отделить классы проекта по зонам ответственности)
Добавляем аннотацию @Mapper (org.mapstruct.Mapper), по которой MapStruct будет генерировать реализацию (под капотом MapStruct будет искать все классы, которые помечены данной аннотацией, и генерировать реализацию по заданным внутри этого интерфейса/абстрактного класса правилам), и указываем componentModel (он нужен в том случае, если мы используем Spring-framework в нашем проекте)
Добавляем абстрактные методы в наш интерфейс, реализацию которых возьмет на себя MapStruct
Без Spring:
Если мы не используем Spring, нужно объявить переменную INSTANCE внутри UserMapper interface, которая позволит получить нам реализацию из интерфейса:
@Mapper
public interface UserMapper {
UserMapper INSTANCE = Mappers.getMapper(UserMapper.class); //add instance to call mapper
UserResponse toUserResponse(User user); //map User to UserResponse
List<UserResponse> toUserResponseList(List<User> users); //map list of User to list of UserResponse
}Контроллеры
Теперь добавим класс UserController, который будет получать запросы и выполнять логику в ответ на запрос:
@RestController
@RequestMapping("/api/users")
@RequiredArgsConstructor
public class UserController {
private final UserRepository userRepository;
private final UserMapper userMapper;
@GetMapping
public ResponseEntity<List<UserResponse>> findAll() {
List<User> users = userRepository.findAll();
List<UserResponse> userResponseList = userMapper.toUserResponseList(users);
return ResponseEntity.ok(userResponseList);
}
@GetMapping("/{id}")
public ResponseEntity<UserResponse> findById(@PathVariable Long id) {
Optional<User> user = userRepository.findById(id);
return user.isPresent()
? ResponseEntity.ok(userMapper.toUserResponse(user.get()))
: ResponseEntity.notFound().build();
}
}Когда мы используем Spring, нам достаточно добавить аннотацию @RequiredArgsConstructor от Lombok, которая сгенерирует конструктор для всех final полей - в данном случае это обьекты UserRepository, UserMapper (Spring подставит нам эти обьекты благодаря принципу DI)
Без Spring:
Если мы не используем Spring - получить реализацию UserMapper мы можем с помощью объявления переменной этого типа в том классе, где хотим использовать конвертер:
private final UserMapper mapper = UserMapper.INSTANCE;Благодаря библиотеке MapStruct, которую мы добавили ранее, во время запуска наш проект будет сканирован, и для всех интерфейсов, обозначенных как @Mapper, будет сгенерирован класс, который реализует все методы, объявленные в нашем маппере.
Теперь посмотрим, какой код сгенерировал нам MapStruct (для этого нажмем shift + shift в IntelijIdea и введем имя UserMapperImpl в поиске Classes)
Как видно, реализация интерфейсного метода максимально проста: вначале идет проверка source-объекта на null, а затем создаются переменные с null значениями, и поочередно вызываются get() методы у target-объекта.
Стопп.. source, target, ты о чем вообще?
Что-ж, давайте вспомним объявление первого метода в нашем UserMapper:
UserResponse toUserResponse(User user);Source объект - это источник, ОТКУДА мы берем данные, в нашем случае это User.
Target объект - это результат, КУДА мы подставляем данные, в нашем случае это UserResponse.
В конце сгенерированной реализации мы видим, что MapStruct берет данные ИЗ User и ставит их В UserResponse. Таким образом, он берет только те поля, которые нужны для создания объекта UserResponse, а в нашем случае поля password у UserResponse нет, значит оно игнорируется!
Теперь посмотрим, какую реализацию сгенерировал MapStruct для получения списка объектов:
Как вы можете заметить, MapStruct делает довольно хитрую вещь: он проходит по списку users и просто вызывает уже сгенерированный ранее метод toUserResponse(), вот и все!
То есть для того, чтобы получить List<UserResponse>, нам нужно только создать сам метод конвертации User ---> UserResponse, а для конвертации всего списка таких же объектов MapStruct пройдется по всем элементам, и вызовет уже существующий метод.
Я уже сохранил 1 запись в базу, через POST метод (его вы увидите дальше, когда будем изучать способ более продвинутого маппинга):
На уровне базы данных сохранились все данные - ID, email, password, username.
Теперь сделаем GET запрос на получение информации о пользователе (напомню, что мы ожидаем ответ БЕЗ поля password, так как скрыли его на этапе маппинга, и передаем клиенту DTO UserResponse):
Как видно, мы не получили секретное поле password, которое хотели скрыть для клиента. Все сработало как надо - в БД все сохранилось как и должно, а в качестве ответа нам пришел UserResponse.
Что же произошло под капотом? Ответ прост: вначале мы получили оригинальную сущность User, с паролем и другими полями, а затем создали новый обьект (DTO) UserResponse, в котором скрыли поле password (этого поля попросту нет).
Более сложный маппинг
Мы разобрались, как выполнять базовый маппинг (конвертацию), но как добавить какую-то логику?
К примеру, при сохранении User, мы хотим поменять его пароль (как и делают в реальных приложениях: пароль шифруют по скрытому алгоритму, и сохраняют его в зашифрованном виде, а при попытке входа в систему, шифруют пароль который пришел из запроса, и сравнивают с уже зашифрованным паролем в Базе Данных).
Таким образом оригинальный пароль знает только сам пользователь, а сама система хранит его уже в зашифрованном виде.
Для начала создадим новую DTO - UserCreateDto, которая будет содержать данные, необходимые для создания пользователя:
В данном примере мы могли бы не создавать UserCreateDto, т.к он содержит те же поля, что и User, но в реальных проектах User имеет аудит-поля, (такие как createdAt, updatedAt, и др.), а также другие данные, которые создаются по умолчанию (к примеру статус пользователя, прим: CREATED) , поэтому желательно создавать отдельную DTO (но также не стоит плодить много DTO-шек, старайтесь везде придерживаться некого баланса).
Создадим UserCreateDto:
public record UserCreateDto(
String username,
String email,
String password) {
} Добавим метод для преобразования UserCreateDto в User:
User fromUserCreateDto(UserCreateDto userCreateDto);А также дополним наш UserController, добавив endpoint для сохранения пользователя:
@PostMapping
public ResponseEntity<UserResponse> createUser(@RequestBody UserCreateDto userCreateDto) {
User user = userMapper.fromUserCreateDto(userCreateDto);
User savedUser = userRepository.save(user);
UserResponse userResponse = userMapper.toUserResponse(savedUser);
return ResponseEntity.ok(userResponse);
}@Mapping - кто ты, воин?
Знакомьтесь, Джо Блэк.. Шучу, @Mapping.
@Mapping - основная аннотация, с которой вы будете сталкиваться большую часть времени. Я не буду приводить тысячи примеров, т.к это займет много времени, и статья превратится в документацию.
Надеюсь, вы еще не забыли про target и source: они нужны чтобы указывать, какие поля нам брать для маппинга.
@Mapping(defaultValue)
Рассмотрим несложный пример:
@Mapping(target = "password", defaultValue = "pass123")
User fromUserCreateDto(UserCreateDto userCreateDto);Скрытый текст
Здесь мы даем инструкцию MapStruct, что хотим установить в поле password нашего target объекта User значение по умолчанию ("pass123"), таким образом пароль из userCreateDto будет игнорироваться, и каждый вызов fromUserCreateDto будет возвращать нам User с полем password = "pass123"
Делаем запрос на сохранение нашего User с паролем "our-custom-password-222":
Так как в ответе нам не приходит пароль (мы скрываем его благодаря маппингу, как было сказано ранее), кажется что ничего не поменялось. А теперь заглянем в базу данных:
Как видно, мы создавали пользователя с паролем "our-custom-password-222", а по факту в базу сохранились совсем другое значение поля password - "test123".
Разберемся, что же произошло:
Мы послали запрос на создание User с полями (первый POST-запрос) на картинке выше
На уровне контроллера нашего приложения вызвался код:
User user = userMapper.fromUserCreateDto(userCreateDto);
User savedUser = userRepository.save(user);В ходе которого мы преобразовали UserCreateDto в User, а в процессе установили значение в поле password самым в User установился пароль со значением defaultValue = "test123", которое было указано в аннотации @Mapping.
Таким образом, defaultValue устанавливает значение, если source == null, а если нужно вне зависимости от условий - это constant. В данном примере source мы не указали, поэтому установилось дефолтное значение.
Пример использования constant:
@Mapping(target = "allowed", constant = "Boolean.FALSE")@Mapping(ignore)
Этот параметр максимально примитивен - он говорит MapStruct, что данное поле мы должны игнорировать:
@Mapping(target = "email", ignore = true)
UserResponse toUserResponse(User user);С помощью "ignore" мы говорим MapStruct: игнорируй поле email при маппинге. В таком случае значение user.email будет проигнорировано, и в UserResponse не будет установлено это значение (это может использоваться для того, чтобы MapStruct не ругался на то, что таких полей нету у source-объекта)
Результат сохранения User будет выглядеть так:
Однако в случае, когда мы имеем множество полей, которые необходимо проигнорировать при маппинге, прописывать @Mapping(ignore = true) слишком долго.
И для такой проблемы у MapStruct есть решение: дополнительное свойство unmappedTargetPolicy у @Mapper, которое указывает, как должен реагировать MapStruct на те поля, которых он не нашел в объекте source:
ERROR - пробрасывание ошибки в случае, когда нужное поле отсутствует
WARN (default) - неприятное красное сообщение, которое пробрасывается по умолчанию, когда вы собираете свой проект
IGNORE - игнорировать все поля, которые не удалось смаппить (такой же эффект, как от "ignore = true")
В коде это будет выглядеть так:
@Mapper(componentModel = MappingConstants.ComponentModel.SPRING,
unmappedTargetPolicy = ReportingPolicy.IGNORE
)@Mapping(expression)
Expression - способ задавать любой Java код. Мы также можем вызывать методы, как внутри UserMapper, так и методы библиотеки.
Как пример, попробуем установливать текущее время в поле password вместо оригинального пароля:
@Mapping(target = "password", expression = "java(LocalDate.now().toString())")
User fromUserCreateDto(UserCreateDto userCreateDto);Важно!
Необходимо поменять наш конфиг, чтобы добавить в импорты LocalDate.class (иначе MapStruct не найдет класс для подстановки в expression, и выкинет ошибку, можете проверить)
Сохраним пользователя через POST и посмотрим, какие данные лежат в БД:
Как видно, в поле password установилось значение текущей даты, несмотря на то, что при создании указывался пароль.
@Named и методы по умолчанию
Представим, что expression нам не хватает - мы хотим реализовать более сложную логику. На помощь приходят аннотации @Named и дефолтные методы.
Давайте создадим default-метод, который будет создавать пароль по следующей логике: брать некую строку, и добавлять к ней свое значение.
default String getPasswordFromUsername(String username) {
return username + " generatedPassword222";
}Тогда наш @Mapping также немного поменяется:
@Mapping(target = "password", expression = "java(getPasswordFromUsername(userCreateDto.username()))")
User fromUserCreateDto(UserCreateDto userCreateDto);В данном примере мы указываем имя метода внутри нашего UserMapper, а также вызываем get()-метод у userCreateDto (геттеры у record-классов именуются без get-префикса)
Делаем запрос, ии..
Что за приколы, скажете вы?
Все просто:
MapStruct сканирует интерфейс на методы, и если видит, что возвращаемое значение и аргумент метода совпадают - смело применяет это ко всем полям. В нашем случае все поля являются String - и MapStruct смело накидал нам ненужной логики.
Давайте исправлять! На помощь идет @Named - аннотация, которая позволяет решить множество проблем, а именно:
Помогает отличить методы, даже если их возвращаемое значение и аргумент совпадают
Позволяет нам использовать qualifiedByName - но к ней мы перейдем чуть позже
Перепишем наш метод:
@Named("getPasswordFromUsername")
default String getPasswordFromUsername(String username) {
return username + " generatedPassword222";
}И получаем ожидаемый результат:
@Mapping(qualifiedByName)
Предыдущий способ, при котором мы вызывали default getPasswordFromUsername() метод через expression - не самый лучший вариант. Его стоит использовать, если мы хотим добавить какую-то логику к значению, которое возвращает метод. В других случаях рекомендуется использовать qualifiedByName()
В данном примере мы не будем менять логику генерации пароля - оставим все как есть. Я лишь покажу вам, как переписать предыдущий пример с использованием qualifiedByName
Изменим наш UserMapper:
@Mapping(target = "password", qualifiedByName = "getPasswordFromUsername", source = "username")
User fromUserCreateDto(UserCreateDto userCreateDto);
@Named("getPasswordFromUsername")
default String getPasswordFromUsername(String username) {
return username + " generatedPassword222";
}Разберемся, какие изменения произошли:
Мы убрали expression, и указали qualifiedByName = "getPasswordFromUsername", где значением является имя, которое стоит в аннотации @Named
Мы указали source = "username", что дает инструкцию для MapStruct взять username из userCreateDto, когда тот будет вызывать метод getPasswordFromUsername(), и передать его в качестве параметра
Таким образом, qualifiedByName служит неким уточнением, которое говорит MapStruct, какой именно метод мы хотим использовать для преобразования значений. Если данный метод принимает какие-либо аргументы, мы можем указать их в source.
Вынесение логики маппинга в отдельные классы
Перед завершением статьи, я бы хотел показать вам еще один способ, который позволит избежать головной боли, с которой столкнулся я.
Представим, что вам нужно сделать отдельный класс для UserMapper (в нем будут собраны все методы, которые нужны для маппинга, а ваш UserMapper будет чист как младенец, вызывая методы из созданного util-класса)
Такое разбиение позволит:
Убрать все вспомогательные методы из UserMapper, что позволит нам видеть, какие поля маппятся, и какие методы вызываются, тем самым увеличив чистоту и понимание кода
Избежать танцев с бубном, если нужно внедрить бины в mapper. В интерфейсе это сделать либо невозможно, либо можно, но такого способа я еще не нашел (потому делал abstract class и добавлял туда нужные бины, помечая аннотацией @Autowired)
Итак, начнем!
Создадим UserMapperUtil в папке ustils.mapper, куда вынесем все методы для маппинга:
@Named("UserMapperUtil")
@Component
@RequiredArgsConstructor
public class UserMapperUtil {
private final Random randomGenerator;
@Named("getPasswordFromUsername")
public String getPasswordFromUsername(String username) {
return username + randomGenerator.nextInt(5000) + 2222;
}
}Мы указали @Named на уровне класса и метода, чтобы в UserMapper вызывать нужные нам методы по имени класса и метода.
Бин Random был создан в ApplicationConfig классе, чтобы продемонстрировать суть такого подхода - мы можем внедрять нужные нам зависимости в Util классы, тем самым вынося всю логику из UserMapper в утилитные классы.
@Configuration
public class ApplicationConfig {
@Bean
public Random randomGenerator() {
return new Random(System.currentTimeMillis() / 72);
}
}Финальное изменение - поменяем интерфейс UserMapper:
@Mapper(componentModel = MappingConstants.ComponentModel.SPRING,
uses = {
UserMapperUtil.class
},
imports = {
LocalDate.class
})
public interface UserMapper {
UserResponse toUserResponse(User user); //map User to UserResponse
List<UserResponse> toUserResponseList(List<User> users); //map list of User to list of UserResponse
@Mapping(target = "password", qualifiedByName = {"UserMapperUtil", "getPasswordFromUsername"}, source = "username")
User fromUserCreateDto(UserCreateDto userCreateDto);
}Здесь мы добавили uses в @Mapper конфигурацию, чтобы MapStruct подгрузил этот класс в целях маппинга, а самое главное - обратились к методу утилитного класса, используя значения, указанные в @Named у UserMapperUtil в qualifiedByName = {"UserMapperUtil", "getPasswordFromUsername"}
Теперь запускаем наш проект снова, и пробуем сохранить User:
Как видите, все сработало! Наш randomGenerator сгенерировал значение и добавил к username.
Ссылки и полезные материалы
Eсли вы дотянули до этого момента - поздравляю!
Надеюсь, что после прочтения этого материала вам стало чуть понятнее и проще, а если хочется изучить MapStruct получше, листайте вниз!
Список источников, которые помогут вам разобрать тему MapStruct еще больше:
