Mapster 异步映射指南：使用 Mapster.Async 在 AfterMapping 中执行异步操作

Mapster 异步映射指南使用 Mapster.Async 在 AfterMapping 中执行异步操作【免费下载链接】MapsterA fast, fun and stimulating object to object Mapper项目地址: https://gitcode.com/GitHub_Trending/ma/MapsterMapster 本身是一个同步的对象映射器但真实业务中经常需要在映射完成后调用异步服务如通过 UserManager 查询用户、访问数据库或调用远程接口。官方扩展包 Mapster.Async 专门解决这一场景它提供AfterMappingAsync配置 API 与AdaptToTypeAsync等异步映射入口让映射管线中也能安全地await异步操作。读完本文你将掌握该包的安装方式、配置与映射的完整写法、底层实现原理基于MapContext的任务收集机制以及同步误用时的防护行为。安装 Mapster.Async在项目引用该扩展包后即可使用本文涉及的全部扩展方法。使用 NuGet 包管理器控制台安装PM Install-Package Mapster.Async也可以使用dotnet add package Mapster.Async或通过 Visual Studio 的“管理 NuGet 程序包”界面安装。从项目结构看该包是一个独立插件项目Mapster.Async.csproj仅引用核心的 Mapster 项目不引入额外运行时依赖因而不会改变原有映射性能特征。配置阶段使用 AfterMappingAsync 声明异步后置操作安装后与同步场景中使用AfterMapping一样可以在TypeAdapterConfig.NewConfigTSource, TDestination()的链式配置中调用AfterMappingAsync唯一的区别是回调可以写成async并执行真实的await。单参数重载只接收目标对象config.NewConfigPoco, Dto() .AfterMappingAsync(async (poco, dto) { var userManager MapContext.Current.GetServiceUserManager(); var user await userManager.FindByIdAsync(poco.UserId); dto.UserName user.Name; });上面的示例同时用到了两个扩展包的配合MapContext.Current.GetServiceTService()来自 Mapster.DependencyInjection它允许在映射配置中从当前请求的依赖注入容器里解析服务。若你的异步回调不需要访问 DI 服务完全可以省略这行。双参数重载同时接收源对象与目标对象源码 TypeAdapterExtensions.cs 提供了两个重载第二个重载同时暴露source与dest适合回调需要读取源对象多个字段的场景config.NewConfigPoco, Dto() .AfterMappingAsync(async (src, dest) { var user await _userService.GetByIdAsync(src.UserId); dest.UserName user.Name; dest.Avatar user.AvatarUrl; });两个重载都是泛型TypeAdapterSetterTDestination/TypeAdapterSetterTSource, TDestination上的扩展方法因此可以与其他链式配置Ignore、Map、BeforeMapping等自由组合并保持链式调用风格。映射阶段三个异步入口配置好AfterMappingAsync之后映射必须通过异步入口执行否则异步任务无法被等待。1. 基于 BuildAdapter 的 AdaptToTypeAsyncvar dto await poco.BuildAdapter() .AdaptToTypeAsyncDto();2. 基于 IMapper 实例的 AdaptToTypeAsync如果你的项目通过 Mapster.DependencyInjection 注入了IMapper服务典型为ServiceMapper则使用var dto await _mapper.From(poco) .AdaptToTypeAsyncDto();3. 更多便捷入口除文档给出的上述两种方式外源码还提供了其他异步映射扩展见 TypeAdapterExtensions.csAdaptToAsyncTDestination(destination)异步映射到已存在的目标对象对应同步方法AdaptTo适用于更新已有 DTO 的场景var dto await poco.BuildAdapter().AdaptToAsync(existingDto);AdaptAsyncTDestination(source)对象级简写等价于source.BuildAdapter().AdaptToTypeAsyncTDestination()var dto await poco.AdaptAsyncDto();AdaptAsyncTDestination(source, config)指定TypeAdapterConfig的简写var dto await poco.AdaptAsyncDto(myConfig);IMapper.MapAsyncTDestination(source)mapper 实例上的简写等价于mapper.From(source).AdaptToTypeAsyncTDestination()var dto await _mapper.MapAsyncDto(poco);底层原理MapContext 与任务收集机制理解异步支持为何能工作关键在 TypeAdapterExtensions.cs 中的实现策略异步回调并不会被编译进映射表达式树而是被降级为一个同步的 AfterMapping 钩子把 Task 收集起来待同步映射完成后统一await。具体流程如下调用AfterMappingAsync时内部调用setter.AfterMapping(...)注册一个同步回调。回调执行时从MapContext.Current?.Parameters中读取以常量ASYNC_KEY Mapster.Async.tasks为键的任务列表若列表不存在立即抛出InvalidOperationException见下文“同步误用防护”否则执行用户传入的异步委托拿到Task把它Add进任务列表。调用AdaptToTypeAsync时源码第 71-82 行先创建ListTask并通过builder.Parameters[ASYNC_KEY] tasks放入IAdapterBuilder的参数集合用MapContextScope.RequiresNew()开启新的MapContext作用域见 MapContextScope.csRequiresNew会强制创建全新上下文忽略外层已存在的上下文在作用域内执行同步映射builder.AdaptToTypeTDestination()此时注册的同步 AfterMapping 钩子会读到任务列表并填充 Task最后await Task.WhenAll(tasks)等待所有异步回调完成再返回映射结果。MapContext本身在 MapContext.cs 中实现在 .NET Standard / .NET 6 编译目标下MapContext.Current使用AsyncLocalMapContext?存储天然支持异步上下文流动Parameters则是一个Dictionarystring, object正是它承担了同步映射钩子与异步入口之间传递任务列表的通道。这也解释了为什么入口方法必须是异步版只有AdaptToTypeAsync这类方法才会向 builder 参数中注入任务列表并最终执行Task.WhenAll。同步误用防护为什么必须用异步入口如果在配置了AfterMappingAsync之后仍然用同步方式调用poco.AdaptDto()由于同步路径不会创建任务列表MapContext.Current.Parameters中取不到ASYNC_KEY对应的值AfterMappingAsync注册的钩子会抛出InvalidOperationException: Mapping contains async function, please use BuildAdapter.AdaptToTypeAsync instead这一点在测试 AsyncTest.cs 的Sync用例中被明确验证配置AfterMappingAsync后调用同步AdaptDto()断言抛出InvalidOperationException。因此一旦映射配置中引入了AfterMappingAsync该映射的所有调用点都必须切换到异步入口这是一个由设计保证的强制约束而非运行时才暴露的隐蔽 bug。多异步回调与嵌套映射注册多个 AfterMappingAsync可以在同一条配置链中注册多个异步回调它们会被收集进同一个任务列表最终由Task.WhenAll并行等待。测试 NestedAsync 展示了同时注册两个回调的用法TypeAdapterConfigDoCarOwnership, DtoCarOwnership.NewConfig() .Ignore(dest dest.Car) .Ignore(dest dest.Owner) .AfterMappingAsync(async (src, dest) { dest.Owner await GetOwner(src.Owner); }) .AfterMappingAsync(async (src, dest) { dest.Car await GetCar(src.Car); });注意该用例中先Ignore了Car与Owner再在异步回调中手工为它们赋值——这是异步场景下的常见组合告诉映射器不要同步映射这些成员由异步逻辑负责填充。异步回调内部再次异步映射异步回调内部也可以再次调用AdaptToTypeAsync完成映射中再映射例如GetCar中通过new DoCar {...}.BuildAdapter().AdaptToTypeAsyncDtoCar()将实体转成 DTO见 AsyncTest.cs说明异步支持对嵌套场景同样成立只要每一层都走异步入口即可。异常传播行为异步回调中抛出的异常会被Task.WhenAll原样传播给调用方。测试 AsyncError 验证回调中throw new Exception(bar)后await poco.BuildAdapter().AdaptToTypeAsyncDto()会将异常抛出且异常消息保持不变。这意味着你无需额外处理回调失败但映射已返回的竞态——只要await异步入口回调错误就能以标准方式向上传播便于统一异常处理。依赖注入配合要点文档示例中的MapContext.Current.GetServiceUserManager()依赖 Mapster.DependencyInjection 包使用前需安装Mapster.DependencyInjection在ConfigureServices中注册TypeAdapterConfig单例与IMapper通常为ServiceMapper其生命周期应不低于所注入服务的最低生命周期在AfterMappingAsync回调中通过MapContext.Current.GetServiceTService()解析服务。仓库样例 Sample.AspNetCore/Startup.cs 展示了完整用法映射配置中从MapContext.Current解析SchoolContext与自定义的NameFormatter服务映射测试 InjectionTest.cs 也验证了MapContext.Current.GetServiceIMockService()在配置求值中的可用性。当异步回调与服务解析结合时请确保整个调用链处于某个 DI 作用域内如 ASP.NET Core 请求作用域否则GetService可能解析不到正确的服务实例。注意事项小结配置了AfterMappingAsync的映射必须使用AdaptToTypeAsync/AdaptToAsync/AdaptAsync/MapAsync等异步入口同步调用会抛InvalidOperationException异步回调在同步映射完成之后、Task.WhenAll之前被统一等待多个回调默认并行执行若回调间存在依赖请自行合并为一个回调或用信号量控制AsyncLocal存储的MapContext保证了在 async/await 跨线程切换时任务列表仍然可达但请勿在回调中手动创建并等待同列表之外的重复 Task该扩展包只负责映射阶段的异步化不改变 Mapster 编译期生成映射委托的机制编译一次后仍按常规映射委托执行性能特征与同步配置保持一致。【免费下载链接】MapsterA fast, fun and stimulating object to object Mapper项目地址: https://gitcode.com/GitHub_Trending/ma/Mapster创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考