Привет, Хабр! Меня зовут Георгий, я С#-разработчик в SimbirSoft. Хочу рассказать об опыте использования библиотеки Mapster: как она может упростить разработку, сэкономить силы и частично избавиться от рутины маппинга.
Данная статья подойдет и тем, кто только собирается открыть для себя мир автомаппинга, и тем, кто хочет найти для себя альтернативу используемой библиотеки. Для полного понимания, что тут будет происходить, желательно обладать базовым пониманием C#, знать о существовании DI и подозревать, что рефлексия не так проста, как кажется. Ну и LINQ с EF.Core, куда же без них (хотя про них достаточно просто когда-то слышать и примерно представлять, зачем они нужны).
Сразу оговорюсь, что в этой статье я собрал не только свой опыт, но и опыт других специалистов — авторов статей и видео, и привел наглядные примеры, как с этим работать. Все ссылки на источники вы найдете внутри.
Если вы пресытились хвалебными отзывами и различными сравнениями мапперов по производительности – сразу пропускайте вводную часть и прыгайте к примерам. Там я подробно расскажу, как этим всем пользоваться.
Вводная часть
Поскольку каждый уважающий себя разработчик хочет, чтобы его проект был удобным, красивым и масштабируемым с точки зрения архитектуры, он старается разделять слои приложения, чтобы в дальнейшем упростить поддержку и развитие. В целом звучит круто, но достаточно сложно, поскольку правильное разделение слоев часто приводит к неконтролируемому росту числа моделей данных, которыми слои между собой обмениваются.
Пример:
Допустим, у нас есть класс репозиторий, который ходит в базу и возвращает нам данные. Мы не хотим, чтобы эта полная модель данных уходила куда-то дальше, поэтому мы преобразуем полученную модель в DTO (Data Transfer Object) и уже возвращаем ее.
В принципе маппинг модели данных в DTO можно сделать и руками, и зачастую это достаточно тривиальная задача. Но насколько же она унылая и рутинная! Для каждой сущности в базе писать свой маппинг, плодить дополнительные классы, где этот маппинг будет жить (мы же не хотим маппить данные прямо в репозитории). Таким образом, у проекта разрастается кодовая база, ее сложнее поддерживать, и в целом, будем честны, не особо хочется каждый раз руками прописывать преобразования объектов. Чуть более подробный пример можно найти в этой статье, вместе с другими фокусами мапстера.
Тут как раз и приходит спасение в виде библиотек автомаппинга, которые позволяют избавиться от написания этого веселья ручками.
Mapster — это имя вам что-нибудь говорит?
Собственно, Mapster – это библиотека, упрощающая маппинг моделей для разработчика, благодаря которой кидаться модельками между слоями приложения становится куда проще. Можно сконцентрироваться на разработке логики приложения, а не на преобразовании этих моделей данных друг в друга.
На данный момент существует много различных автомапперов, и их уже не раз сравнивали между собой. Например, этот прекрасный человек в своем видео сравнил их по производительности.
Для тех, кто любит цифры
Как я уже говорил ранее, только ленивый не сравнивал по производительности популярные инструменты маппинга, ну а я человек не ленивый (почти), поэтому тоже пришел поделиться своими наблюдениями.
Сравнивать будем AutoMapper, Mapster в его «одноклеточной» вариации, Mapster в режиме кодогенерации, Mapperly (поскольку он нравится многим) и ручной маппинг.
Маппить будем следующие модельки:
public class DocumentDto { public Guid Id { get; set; } public string Name { get; set; } public string Description { get; set; } public string Author { get; set; } public int PagesCount { get; set; } public bool IsPublic { get; set; } public string[] Tags { get; set; } public DateTime Created { get; set; } public DateTime Modified { get; set; } public DateTime? Deleted { get; set; } }и
public class Document { public Guid Id { get; set; } public string Name { get; set; } public string Description { get; set; } public string Author { get; set; } public int PagesCount { get; set; } public bool IsPublic { get; set; } public string[] Tags { get; set; } public DateTime Created { get; set; } public DateTime Modified { get; set; } public DateTime? Deleted { get; set; } }Ничего сложного и необычного в них нет, они достаточно простые и наглядные.
Заполним входную модельку в отдельном статическом классе, чтобы удобно было ее прокидывать в бенчмарки:
public static class TestData { public static DocumentDto TestDocument = new() { Id = Guid.NewGuid(), Name = "DocumentName", Author = "DocumentAuthor", Description = "DocumentDescription", IsPublic = true, PagesCount = 100, Created = DateTime.Now, Modified = DateTime.Now, Deleted = null, Tags = new string[] { "Book", "Horror", "Adventure" } }; } Как создавать, конфигурировать и прокидывать тестируемые мапперы, я рассказывать не буду, поскольку это другая тема (кроме мапстера, о нем речь пойдет позже).
Но класс бенчмарков будет выглядеть примерно так
[MemoryDiagnoser(false)] [Orderer(BenchmarkDotNet.Order.SummaryOrderPolicy.FastestToSlowest)] public class Benchmarks { private readonly DocumentDto _documentDto = TestData.TestDocument; private readonly IMapper _autoMapper; private readonly MapperlyMapper _mapperlyMapper; private readonly MapsterMapper _mapsterMapper; public Benchmarks() { var mapperConfig = new MapperConfiguration(cfg => { cfg.CreateMap<DocumentDto, Document>(); }); _autoMapper = mapperConfig.CreateMapper(); _mapperlyMapper = new MapperlyMapper(); _mapsterMapper = new MapsterMapperImpl(); } [Benchmark] public Document AutoMapper() { return _autoMapper.Map<Document>(_documentDto); } [Benchmark] public Document Mapster() { return _documentDto.Adapt<Document>(); } [Benchmark] public Document Mapperly() { return _mapperlyMapper.Map(_documentDto); } [Benchmark] public Document MapsterMapper() { return _mapsterMapper.Map(_documentDto); } [Benchmark] public Document ManualMapping() { return _documentDto.Map(); } }Сразу отмечу, что Mapster в данном случае – это как раз «одноклеточное» использование, а MapsterMapper – явное использование кодогенерации.
Немного об окружении:
-
Процессор: AMD Ryzen 7 3700x;
-
Среда разработки: Visual Studio 2022;
-
Версия .NET 7.
Пускаем тесты, и видим результат:
Mapperly оказался самым быстрым и наименее прожорливым среди всех автомапперов. Всё, господа, расходимся, тема закрыта.
Как и ожидалось, ручной маппинг оказался самым быстрым решением, однако, Mapperly был очень близок к нему (по памяти так вообще идентичны). С отставанием примерно в 2 раза от Mapperly расположился Mapster в режиме кодогенерации, «простейший» мапстер и замыкающим выступает Automapper. В целом, мапстер показал достойный результат, но его главная фишка раскроется уже непосредственно в применении, о котором речь пойдет в практическом разделе.
Коротко об особенностях Mapster
Если говорить об основных отличительных особенностях этой библиотеки, то можно выделить следующее:
-
Кодогенерация
Mapster использует подход кодогенерации, что позволяет ему достаточно быстро работать. Не сказать, что это какой-то уникальный подход, но тот же AutoMapper использует рефлексию, что сказывается на его производительности.
-
Возможность примитивного использования мапстера из коробки
Для маппинга примитивных моделей с совпадающими полями, мапстер действительно просто и удобно использовать. Даже DI контейнер не нужен. Пример будет в практическом разделе.
-
Гибкая возможность настройки
В данном пункте я имею ввиду не только возможность задавать кастомный маппинг сложных моделей данных в конфиге, но и настройку билда проекта, при которой не получится запустить приложение, если не будет задан маппинг всех полей для моделей. Подробнее об этом будет описано в практике.
Дополнительно оставлю ссылку на статью, где более подробно описано сравнение мапстера и автомаппера с конкретными примерами реализации.
Теперь предлагаю перейти непосредственно к практическим примерам.
Практика
Дальнейшие примеры будут рассмотрены для .NET 7 в Visual Studio 2022 (среда разработки не принципиальна).
Для приложения будем использовать следующие модельки:
-
User – модель данных в базе
public class User { public Guid Id { get; set; } public string Name { get; set; } public string Email { get; set; } public string Password { get; set; } }-
UserDto – моделька, которую мы хотим отдавать
public class UserDto { public Guid Id { get; set; } public string Name { get; set; } public string Email { get; set; } }-
UserDomainModel — моделька, которую мы хотим отдавать, но с подвохом
public class UserDomainModel { public Guid UserId { get; set; } public string UserName { get; set; } public string UserEmail { get; set; } }Непосредственно с ними мы и будем развлекаться, но сначала напишем простой маппинг для User и UserDto.
public static UserDto Map(this User user) { return new UserDto { Id = user.Id, Name = user.Name, Email = user.Email }; }и подтянем необходимые NuGet пакеты:
По опыту использования, для себя я смог выделить четыре типа использования мапстера:
-
Mapster как аналог Automapper;
-
«Одноклеточный» Mapster;
-
Mapster и работа с базой;
-
Mapster и фокусы кодогенерации.
По такому порядку и пойдем.
Mapster как аналог Automapper
Для тех, кто пользовался AutoMapper, достаточно привычный сценарий использования, где мы создаем класс маппера, закидываем его в DI-контейнер и используем по необходимости.
Создадим файл конфигурации:
public class RegisterMapper : IRegister { public void Register(TypeAdapterConfig config) { config.NewConfig<User, UserDto>() .RequireDestinationMemberSource(true); } }IRegister находится в пространстве имен Mapster.
RequireDestinationMemberSource указывает, что проект не соберется в случае, если невозможно автоматически преобразовать одну модель в другую (в таком случае, нужно руками прописать маппинг свойств), но в нашем случае названия свойств у User и UserDto совпадают, поэтому не требуется больше никаких дополнительных настроек, только зарегистрировать конфиг и сам маппер в DI:
builder.Services.AddSingleton(() => //Добавляем конфиг { var config = new TypeAdapterConfig(); new RegisterMapper().Register(config); return config; }); builder.Services.AddScoped<IMapper, ServiceMapper>(); //Добавляем сам мапперК достоинствам такого подхода можно отнести то, что мы можем использовать Mapster там, где он нам необходим и проделывать интересные фокусы, о которых мы поговорим позже.
«Одноклеточный» Mapster
Из названия понятно, что это максимально простой способ использования этой библиотеки. Собственно, с ним я и сталкивался чаще всего. Дело в том, что для маппинга моделей нам нужно всего лишь вызывать метод .Adapt у исходных моделей.
var user = new User //Создаем сущность User { Id = Guid.NewGuid(), Name = "Tom", Email = "Tom@mail.com", Password = "123" }; var userDto = user.Adapt<UserDto>(); //Маппим user в userDtoВсё, конец. Действительно просто и лаконично, а самое прекрасное то, что если у целевой модели и модели источника названия полей совпадают, то мапстер сам смаппит все их значения. И даже если у нас сложная модель, он всё сделает сам, обходя объект рекурсивно. Согласитесь, экономия кучи времени в случае, если у нас модель в модели в модели с кучей полей с совпадающими названиями.
Однако если поля будут иметь различные названия, тут уже придется поработать руками, иначе в итоге мы получим дефолтные значения.
Чтобы всё работало как надо, создаем конфиг, где указываем все правила маппинга для всех моделей:
public class MapsterConfig { public MapsterConfig() { TypeAdapterConfig<User, UserDomainModel>.NewConfig() .Map(dest => dest.UserId, src => src.Id) .Map(dest => dest.UserName, src => src.Name) .Map(dest => dest.UserEmail, src => src.Email); } }после чего регистрируем его в DI.
var mapsterConfig = new MapsterConfig(); builder.Services.AddSingleton<MapsterConfig>();На этом наши манипуляции заканчиваются, и мы снова радуемся простоте и лаконичности.
Mapster и работа с базой
В случае, если у нас в базе лежит модель с кучей ненужных для DTO полей, а тянуть кучу лишних данных не хочется, можно обратиться к мапстеру и попросить его сразу возвращать DTOшки из базы. Он будет настолько любезен, что даже запрос будет сформирован с учетом только необходимых нам полей. Примером же будет служить наш бедный на поля юзер.
Так выглядит классический запрос на получение всех юзеров из базы:
var users = await _context.Users.ToListAsync(); var result = users.Select(x => x.Map());А так будет выглядеть запрос, если мы воспользуемся мапстером:
var users = _mapper.From(_context.Users).ProjectToType<UserDto>(); var result = await users.ToListAsync();_mapper в рассматриваемом случае – маппер из первого сценария использования, где мы прокидываем его через DI.
Разница не сказать что большая, но самое интересное происходит в запросах, которые собирает Ef.Core, обращаясь к базе данных:
Сверху показан запрос, который генерируется в случае использования мапстера, а снизу – обычный. Таким образом, если у нас хранятся действительно тяжелые модели, которые затратно тянуть в память, это очень даже рабочий вариант использования.
На практике такое встречается крайне редко (настолько, что я никогда такого не видел в проектах), но возможность всё равно крайне интересная.
Рассмотренный способ применения можно использовать в высоконагруженных приложениях, где идет большая нагрузка на базу данных, а кеширование по той или иной причине не завезли. Такое применение позволит избежать лишней нагрузки на базу, сократит трафик, который идет к ней и от нее, что в целом положительно скажется на скорости работы приложения.
Mapster и фокусы кодогенерации
Помимо всего прочего Mapster, а если быть точнее Mapster.Tool, умеет в кодогенерацию при сборке проекта. Это позволяет автоматически генерировать классы мапперов во время сборки проекта. Инструкция по установке находится на страничке в гитхабе.
После установки, производим следующие операции:
Добавляем в файл проекта (.csproj) следующий код для генерации:
<Target Name="Mapster" AfterTargets="AfterBuild"> <Exec WorkingDirectory="$(ProjectDir)" Command="dotnet tool restore" /> <Exec WorkingDirectory="$(ProjectDir)" Command="dotnet mapster model -a "$(TargetDir)$(ProjectName).dll"" /> <Exec WorkingDirectory="$(ProjectDir)" Command="dotnet mapster extension -a "$(TargetDir)$(ProjectName).dll"" /> <Exec WorkingDirectory="$(ProjectDir)" Command="dotnet mapster mapper -a "$(TargetDir)$(ProjectName).dll"" /> </Target> <ItemGroup> <Generated Include="**\*.g.cs" /> </ItemGroup> <ItemGroup> <Folder Include="Mappers\" /> </ItemGroup> <Target Name="CleanGenerated"> <Delete Files="@(Generated)" /> </Target>И для очистки:
<ItemGroup> <Generated Include="**\*.g.cs" /> </ItemGroup> <Target Name="CleanGenerated"> <Delete Files="@(Generated)" /> </Target>Очистку можно выполнять из командной строки с помощью команды
dotnet msbuild -t:CleanGeneratedНо это необходимо в том случае, если мы меняем интерфейсы маппера.
Далее нам необходимо создать интерфейс маппера, по которому будет генерироваться сама реализация маппинга.
В нем указываем, все, что хотим маппить, и накидываем на сам интерфейс атрибут [Mapper]:
[Mapper] public interface IUserMapper { UserDto MapTo(User user); User MapTo(UserDto userDto); }И засовываем это всё в DI.
builder.Services.AddScoped<IUserMapper, UserMapper>();В целом всё готово. Просто вызываем в нужном нам месте маппинг:
var userDto = _userMapper.MapTo(user);И собираем проект. После чего можно посмотреть на сгенерировавшийся класс:
public partial class UserMapper : IUserMapper { public UserDto MapTo(User p1) { return p1 == null ? null : new UserDto() { Id = p1.Id, Name = p1.Name, Email = p1.Email }; } public User MapTo(UserDto p2) { return p2 == null ? null : new User() { Id = p2.Id, Name = p2.Name, Email = p2.Email }; } }А помните в самом начале раздела код маппинга, который я писал сам руками? Мапстер сгенерировал его даже лучше меня (привет, проверка на null).
Кстати, так выглядит сгенерированный класс:
Генерировать можно не только маппинги по интерфейсам, но и модельки и методы расширений, но это уже к документации.
Данный подход я тоже пока не встречал в реальных проектах, но выглядит он весьма интересно и перспективно. Более подробно об этих фичах рассказывалось тут.
Что касается применения, то можно рассмотреть опять же высоконагруженные системы, где мы гонимся за минимизацией расходов памяти и времени, которые использует приложение. Также данный подход позволяет сократить затрачиваемое время разработчиков на внедрение новой функциональности и поиск ошибок, связанных с некорректными возвращаемыми данными.
UPD: Усложняем примеры
С простым юзером в целом и так всё понятно, теперь поэкспериментируем с типами данных. Для этого возьмем новые модельки:
Модель здания
public class House { public Guid Id { get; set; } public string Name { get; set; } public string Number { get; set; } public DateTime BuildStarDate { get; set; } public string BuildFinishDate { get; set; } public BuildingType BuildingType { get; set; } public Guid HouseTypeId { get; set; } public HouseType HouseType { get; set; } }Модель типа здания
public class HouseType { public Guid Id { get; set; } public string TypeName { get; set; } }Enun для типа здания (не такой, как прошлый тип)
public enum BuildingType { Hospital = 0, Theater = 1 }Да, топорный пример, но будет вполне показательным.
А мапить это будем в 2 модельки домов.
-
Попроще:
public class HouseDto { public Guid Id { get; set; } public string Name { get; set; } public int Number { get; set; } public string BuildStarDate { get; set; } public DateTime BuildFinishDate { get; set; } public BuildingType BuildingType { get; set; } public HouseTypeDto HouseType { get; set; } }К ней вдогонку добавим DTOшку для типа:
public class HouseTypeDto { public Guid Id { get; set; } public string TypeName { get; set; } }-
И поинтереснее:
public class FlatHouseDto { public Guid Id { get; set; } public string Name { get; set; } public int Number { get; set; } public string BuildStarDate { get; set; } public DateTime BuildFinishDate { get; set; } public BuildingType BuildingType { get; set; } public string HouseTypeName { get; set; } }На этом подготовка закончена. Обращаю внимание, что у House и (Flat)HouseDto типы данных для дат поменяны местами, и поле Number отличается (int vs string).
Пойдем итеративно, начиная с самого ленивого способа.
Для вывода списка всех домов из базы проведем следующую манипуляцию через .Adapt:
var houses = await _houseRepository.GetAllAsync(); var result = houses.Select(x => x.Adapt<HouseDto>()).ToList();Вызовем метод, получим данные:
Всё как и ожидалось: мапстер рекурсивно смаппил всё, что видел, привел даты к нужному типу (тут прошу обратить внимание, что есть строка, а что дата).
Теперь пускаем метод для FlatHouseDto
houseTypeName вернулся пустой, поскольку мапстер не смог понять, что с этим делать. Добавляем правило для одного свойства в конфиг, который создавали еще для юзера в простых примерах:
TypeAdapterConfig<House, FlatHouseDto>.NewConfig() .Map(dest => dest.HouseTypeName, src => src.HouseType.TypeName);И получаем следующий результат:
Радуемся добавленным двум строчкам кода.
Теперь посмотрим в сторону автогенерации. Создадим интерфейс:
[Mapper] public interface IHouseMapper { HouseDto MapTo(House house); FlatHouseDto MapToFlat(House house); }И запускаем билд проекта (при условии, что мы проделали операции из простых примеров).
Иии… тут мапстер уже не очень молодец, но старается. Вот что он смог сгенерировать:
public partial class HouseMapper : IHouseMapper { public HouseDto MapTo(House p1) { return p1 == null ? null : new HouseDto() { Id = p1.Id, Name = p1.Name, Number = p1.Number == null ? 0 : int.Parse(p1.Number), BuildStarDate = p1.BuildStarDate.ToString(), BuildFinishDate = p1.BuildFinishDate == null ? default(DateTime) : DateTime.Parse(p1.BuildFinishDate), BuildingType = p1.BuildingType, HouseType = p1.HouseType == null ? null : new HouseTypeDto() { Id = p1.HouseType.Id, TypeName = p1.HouseType.TypeName } }; } public FlatHouseDto MapToFlat(House p2) { return p2 == null ? null : new FlatHouseDto() { Id = p2.Id, Name = p2.Name, Number = p2.Number == null ? 0 : int.Parse(p2.Number), BuildStarDate = p2.BuildStarDate.ToString(), BuildFinishDate = p2.BuildFinishDate == null ? default(DateTime) : DateTime.Parse(p2.BuildFinishDate), BuildingType = p2.BuildingType }; } }Всё круто, всё здорово, но HouseTypeName опять потерялся. Тут опять придется добавлять маппинг руками. Однако, замечу, что мы не потеряем все, что дописали. Генерация заново происходит только в том случае, если у нас в целом нет реализации интерфейса. Во всех остальных случаях — всё ожидаемо, никаких случайных выстрелов с удалением важного функционала не происходит (до тех пор, пока мы сами не почистим проект).
Выводы
Хотелось бы сказать, что Mapster действительно способен упростить разработку и избавить от части рутины. Им удобно и приятно пользоваться, а «одноклеточный» сценарий так просто находка для любителей не заморачиваться по мелочам. Данная статья показывает основные, но далеко не полные возможности этой библиотеки. Пускай и круг решаемых задач глобально ограничивается работой с преобразованием одних данных в другие, но гибкость этой библиотеки позволяет не только упростить процесс самой разработки, но и улучшить качество поддержки, что положительно повлияет на скорость нахождения багов или доработки приложения.
Спасибо за внимание!
Больше авторских материалов для backend-разработчиков от моих коллег читайте в соцсетях SimbirSoft – ВКонтакте и Telegram.
ссылка на оригинал статьи https://habr.com/ru/articles/797073/
Добавить комментарий