AutoMapper 使用手册：从入门到精通

一、AutoMapper简介与核心价值

AutoMapper 是一个基于 .NET 平台的对象-对象映射库，其核心价值在于通过约定优于配置的原则，将繁琐的属性复制代码转化为简洁的配置声明。在传统开发中，开发者需手动编写大量重复代码实现 DTO（数据传输对象）与 Domain Model（领域模型）之间的转换，而 AutoMapper 通过反射机制和配置规则，自动完成属性匹配与值传递，显著提升开发效率并降低维护成本。

典型应用场景包括：

1. 分层架构中的数据转换：在表现层（UI）、业务逻辑层（BLL）与数据访问层（DAL）之间传递不同结构的对象。
2. API 开发中的 DTO 映射：将数据库实体映射为轻量级 DTO，避免暴露敏感字段或复杂关联。
3. 测试数据生成：快速构建测试用例所需的模拟对象。

二、基础使用：快速上手

1. 环境准备

通过 NuGet 安装 AutoMapper 核心包：

Install-Package AutoMapper

对于 ASP.NET Core 项目，推荐同时安装扩展包以简化依赖注入：

Install-Package AutoMapper.Extensions.Microsoft.DependencyInjection

2. 基础映射配置

步骤 1：定义源对象与目标对象

public class Source {
    public int Id { get; set; }
    public string Name { get; set; }
    public DateTime CreatedDate { get; set; }
}
public class Destination {
    public int Id { get; set; }
    public string FullName { get; set; }
    public string CreationYear { get; set; }
}

步骤 2：创建映射配置

var config = new MapperConfiguration(cfg => {
    cfg.CreateMap<Source, Destination>()
        .ForMember(dest => dest.FullName, opt => opt.MapFrom(src => src.Name))
        .ForMember(dest => dest.CreationYear, opt => opt.MapFrom(src => src.CreatedDate.Year.ToString()));
});

步骤 3：执行映射

var mapper = config.CreateMapper();
var source = new Source { Id = 1, Name = "Test", CreatedDate = DateTime.Now };
var destination = mapper.Map<Destination>(source);

3. ASP.NET Core 集成

在 Startup.cs 中配置服务：

public void ConfigureServices(IServiceCollection services) {
    services.AddAutoMapper(typeof(Startup)); // 自动扫描程序集中的所有配置
    // 或显式指定配置类
    // services.AddAutoMapper(cfg => cfg.AddProfile<MyMappingProfile>());
}

三、高级映射技巧

1. 扁平化映射

将复杂对象的属性映射到扁平结构：

public class Order {
    public int OrderId { get; set; }
    public Customer Customer { get; set; }
}
public class OrderDto {
    public int OrderId { get; set; }
    public string CustomerName { get; set; }
}
// 配置
cfg.CreateMap<Order, OrderDto>()
    .ForMember(dest => dest.CustomerName, opt => opt.MapFrom(src => src.Customer.Name));

2. 反向映射

支持从目标对象反向映射到源对象：

cfg.CreateMap<Source, Destination>().ReverseMap();

3. 自定义值解析器

处理复杂转换逻辑：

public class CustomResolver : IValueResolver<Source, Destination, string> {
    public string Resolve(Source source, Destination destination, string destMember, ResolutionContext context) {
        return source.Name?.ToUpper() ?? "DEFAULT";
    }
}
// 配置中使用
cfg.CreateMap<Source, Destination>()
    .ForMember(dest => dest.FullName, opt => opt.MapFrom<CustomResolver>());

4. 条件映射

根据条件决定是否映射：

cfg.CreateMap<Source, Destination>()
    .ForMember(dest => dest.FullName, opt => opt.Condition((src, dest, srcVal) => !string.IsNullOrEmpty(srcVal)));

四、性能优化与最佳实践

1. 预编译映射

对于高频调用的映射，使用预编译：

var configuration = new MapperConfiguration(cfg => cfg.CreateMap<Source, Destination>());
var mapper = configuration.CreateMapper();
var typeMap = mapper.ConfigurationProvider.FindTypeMapFor<Source, Destination>();
var mappingFunc = mapper.CreateTypeMap<Source, Destination>().GetUnmappedMembers(); // 获取映射函数

2. 避免反射开销

• 批量初始化 MapperConfiguration 并复用
• 避免在循环中动态创建映射配置

3. 调试与验证

使用 AssertConfigurationIsValid 验证配置：

var config = new MapperConfiguration(cfg => {
    cfg.CreateMap<Source, Destination>();
});
config.AssertConfigurationIsValid(); // 抛出异常如果存在未映射属性

4. 常见问题解决方案

问题 1：未映射属性错误

原因：目标对象存在源对象未配置的属性
解决：显式忽略或配置映射

cfg.CreateMap<Source, Destination>()
    .ForAllOtherMembers(opt => opt.Ignore());

问题 2：循环引用

场景：A 映射到 B，B 又映射回 A
解决：使用 MaxDepth 限制递归深度

cfg.CreateMap<A, B>()
    .MaxDepth(1);

五、实际项目中的架构建议

1. 映射配置组织

• 按功能模块划分：将相关实体的映射配置放在同一 Profile 类中

  public class OrderMappingProfile : Profile {
    public OrderMappingProfile() {
        CreateMap<Order, OrderDto>();
        CreateMap<OrderItem, OrderItemDto>();
    }
  }

• 使用特性标记：通过自定义特性自动注册映射

  [AutoMap(typeof(Destination))]
  public class Source { ... }

2. 单元测试策略

• 测试映射完整性：验证所有必需属性是否被正确映射
• 测试边界条件：如 null 值处理、类型转换异常

3. 与其他库集成

• 与 Entity Framework Core 结合：在查询中直接映射

  var orders = context.Orders
    .ProjectTo<OrderDto>(mapper.ConfigurationProvider)
    .ToList();

• 与 MediatR 结合：在请求/响应对象间自动转换

六、总结与展望

AutoMapper 通过其强大的配置能力和灵活的扩展机制，已成为 .NET 生态中对象映射的标准解决方案。掌握其高级特性（如自定义解析器、条件映射）和性能优化技巧，能够显著提升代码质量与开发效率。未来随着 .NET 版本的演进，AutoMapper 将持续优化反射性能并增强对新语言特性的支持。

建议实践：

1. 为每个项目建立统一的 MappingProfile 基类
2. 将复杂映射逻辑封装为可复用的解析器
3. 在 CI 流程中加入映射配置验证步骤

通过系统化地应用 AutoMapper，开发者能够将更多精力投入到业务逻辑实现，而非重复的对象转换工作。