MapStruct — смаппь меня, если сможешь
Исходный код проекта: github
В этой статье мы разберемся с такими понятиями как DTO, Mapping, а также примерами их использования (в самом конце вы увидите полезные ссылки на доп источники по теме).
MapStruct
Я потратил на изучение данной библиотеки немало нервных клеток, и уверен, что узнал далеко не все способы и лайфхаки, но постарался донести информацию с практической стороны, чтобы вы с самого старта не испытывали «нежданчиков» и сэкономили свое время в попытках найти работающий способ.
Hidden text
СПОЙЛЕР: в данном проекте я не использую слой service, а обращаюсь к repository напрямую, и также максимально упростил реализацию, чтобы сфокусироваться на рассматриваемой теме.
Начальные данные
Смоделируем ситуацию: у нас есть некий сервис, который работает с пользователями. Сохраняет, обновляет и возвращает данные о пользователях. Стандартный набор полей сущности User выглядит так: id, username, email, password.
сущность User
Когда пользователь регистрируется в нашей системе, мы сохраняем переданные данные в БД (базу данных), и затем возвращаем сохраненные данные, а также статус, в зависимости от результата операции (успех или ошибку).
Вопрос: как вы считаете, стоит ли включать в ответ клиенту поле password при успешном сохранении пользователя?
Hidden text
Спойлер: нет!
Конечно, можно обнулить поле password, и передать его клиенту -, но мы можем забыть выполнить обнуление пароля, и передать его в ответе -, а там на стороне клиента данные могут спокойно перехватить и использовать в своих целях (помните, что клиент это не только браузер — могут быть другие приложения, которые используют наш API).
Именно поэтому мы создадим дополнительный объект UserResponse, который и является DTO, и будет иметь только те поля, которые должен получить клиент, исключая поле password, как показано на рисунке ниже:
сущность UserResponse
Мы, как разработчики, должны заботиться о безопасности на своей стороне. Если есть возможность и необходимость скрыть некоторые поля, которые как пример не нужны, либо представляют особую важность (в данном случае поле 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), все делается автоматически, ну или почти…
Зачем нам вообще нужен маппер, к чему лишние технологии?
Hidden text
Хороший вопрос. В процессе работы над реальными задачами, вам понадобится добавлять дополнительную логику (устанавливать значения по умолчанию, как пример текущее время, или другие константы / enum-значения, преобразовывать данные (шифровать пароль, генерировать никнейм), и т.п).
Проще использовать уже готовую библиотеку, которая сэкономит ваше время, нервы, и позволит реализовывать более гибкое поведение для конкретных ситуаций.
Теория — хорошо, а практика — еще лучше!
Для начала нам надо выбрать систему сборки для проекта (в данном примере я использую Gradle, но пример подключения библиотеки для Maven будет также приведен ниже).
Gradle:
dependencies {
//...
// MapStruct
implementation 'org.mapstruct:mapstruct:1.5.5.Final'
annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.5.Final'
}
Maven:
1.5.5.Final
...
org.mapstruct
mapstruct
${org.mapstruct.version}
...
org.apache.maven.plugins
maven-compiler-plugin
3.8.1
1.8
org.mapstruct
mapstruct-processor
${org.mapstruct.version}
Создадим сущность 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 toUserResponseList(List 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 toUserResponseList(List 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> findAll() {
List users = userRepository.findAll();
List userResponseList = userMapper.toUserResponseList(users);
return ResponseEntity.ok(userResponseList);
}
@GetMapping("/{id}")
public ResponseEntity findById(@PathVariable Long id) {
Optional 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)
сгенерированная MapStruct имплементация метода toUserResponse ()
Как видно, реализация интерфейсного метода максимально проста: вначале идет проверка source-объекта на null, а затем создаются переменные с null значениями, и поочередно вызываются get () методы у target-объекта.
Стопп… source, target, ты о чем вообще?
Что-ж, давайте вспомним объявление первого метода в нашем UserMapper:
UserResponse toUserResponse(User user);
Source объект — это источник, ОТКУДА мы берем данные, в нашем случае это User.
Target объект — это результат, КУДА мы подставляем данные, в нашем случае это UserResponse.
В конце сгенерированной реализации мы видим, что MapStruct берет данные ИЗ User и ставит их В UserResponse. Таким образом, он берет только те поля, которые нужны для создания объекта UserResponse, а в нашем случае поля password у UserResponse нет, значит оно игнорируется!
Теперь посмотрим, какую реализацию сгенерировал MapStruct для получения списка объектов:
сгенерированная MapStrcut имплементация метода toUserResponseList ()
Как вы можете заметить, MapStruct делает довольно хитрую вещь: он проходит по списку users и просто вызывает уже сгенерированный ранее метод toUserResponse (), вот и все!
То есть для того, чтобы получить List
, нам нужно только создать сам метод конвертации User ---> UserResponse, а для конвертации всего списка таких же объектов MapStruct пройдется по всем элементам, и вызовет уже существующий метод.
Я уже сохранил 1 запись в базу, через POST метод (его вы увидите дальше, когда будем изучать способ более продвинутого маппинга):
На уровне базы данных сохранились все данные — ID, email, password, username.
Теперь сделаем GET запрос на получение информации о пользователе (напомню, что мы ожидаем ответ БЕЗ поля password, так как скрыли его на этапе маппинга, и передаем клиенту DTO UserResponse):
ответ на запрос получения пользователя с ID = 1
Как видно, мы не получили секретное поле 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 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.
Это основная аннотация, с которой вы будете сталкиваться большую часть времени. Я не буду приводить тысячи примеров, т.к это займет много времени, и статья превратится в документацию.
Надеюсь вы еще не забыли про target и source: они нужны чтобы указывать, какие поля нам брать для маппинга.
@Mapping (defaultValue)
Рассмотрим несложный пример:
@Mapping(target = "password", defaultValue = "pass123")
User fromUserCreateDto(UserCreateDto userCreateDto);
Hidden text
Здесь мы даем инструкцию MapStruct, что хотим установить в поле password нашего target объекта User значение по умолчанию («pass123»), таким образом пароль из userCreateDto будет игнорироваться, и каждый вызов fromUserCreateDto будет возвращать нам User с полем password = «pass123»
Делаем запрос на сохранение нашего User с паролем «our-custom-password-222»:
ответ после создания сущности User
Так как в ответе нам не приходит пароль (мы скрываем его благодаря маппингу, как было сказано ранее), кажется что ничего не поменялось. А теперь заглянем в базу данных:
состояние базы данных после создания сущности User
Как видно, мы создавали пользователя с паролем «our-custom-password-222», а по факту в базу сохранились совсем другое значение поля password — «test123».
Разберемся, что же произошло:
Мы послали запрос на создание User с полями (первый POST-запрос) на картинке выше
На уровне контроллера нашего приложения вызвался код:
User user = userMapper.fromUserCreateDto(userCreateDto);
User savedUser = userRepository.save(user);
В ходе которого мы преобразовали UserCreateDto в User, а в процессе установили значение в поле password самым в User установился пароль со значением defaultValue = «pass123», которое было указано в аннотации @Mapping.
Таким образом мы выяснили, что defaultValue устанавливает указанное значение для всех полей, вне зависимости от условий.
@Mapping (ignore)
Этот параметр максимально примитивен — он говорит MapStruct, что данное поле мы должны игнорировать:
@Mapping(target = "email", ignore = true)
UserResponse toUserResponse(User user);
С помощью «ignore» мы говорим MapStruct: игнорируй поле email при маппинге. В таком случае значение user.email будет проигнорировано, и в UserResponse не будет установлено это значение (это может использоваться для того, чтобы MapStruct не ругался на то, что таких полей нету у source-объекта)
Результат сохранения User будет выглядеть так:
как видно, благодаря игнорированию, поле «email» является пустым
Однако в случае, когда мы имеем множество полей, которые необходимо проигнорировать при маппинге, прописывать @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 установилась дата
Как видно, в поле password установилось значение текущей даты, несмотря на то, что при создании указывался пароль.
@Named & Default Methods
Представим, что 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";
}
И получаем ожидаемый результат:
ответ на создание сущности User
@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 toUserResponseList(List 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
Как видите, все сработало! Наш randomGenerator сгенерировал значение и добавил к username.
Ссылки и полезные материалы
Eсли вы дотянули до этого момента — поздравляю!
Надеюсь, что после прочтения этого материала вам стало чуть понятнее и проще, а если хочется изучить MapStruct глубже, листайте ниже!
Список источников, которые помогут вам разобрать тему MapStruct еще больше: