AutoMapper 使用手册：从基础到进阶的完整指南

一、AutoMapper 核心概念解析

AutoMapper 是一个基于.NET平台的对象-对象映射库，通过约定优于配置的原则，将源对象属性自动映射到目标对象，消除手动赋值代码。其核心价值体现在三个方面：

1. 代码简洁性：将重复的属性赋值逻辑抽象为配置，减少样板代码
2. 维护性提升：当对象结构变更时，只需修改映射配置而非逐个修改赋值语句
3. 类型安全：编译时检查映射关系，避免运行时属性名拼写错误

典型应用场景包括：DTO与实体类的转换、视图模型构建、API响应数据封装等。据统计，使用AutoMapper可使映射代码量减少70%以上。

二、基础配置与快速入门

1. 环境准备

通过NuGet安装核心包：

Install-Package AutoMapper
Install-Package AutoMapper.Extensions.Microsoft.DependencyInjection

在ASP.NET Core中配置服务：

// Startup.cs 或 Program.cs
services.AddAutoMapper(typeof(Program).Assembly);
// 或指定多个程序集
// services.AddAutoMapper(Assembly.GetExecutingAssembly(), Assembly.Load("OtherAssembly"));

2. 创建映射配置

// 方式1：Profile基类
public class MappingProfile : Profile
{
    public MappingProfile()
    {
        CreateMap<Source, Destination>()
            .ForMember(dest => dest.FullName, opt => opt.MapFrom(src => $"{src.FirstName} {src.LastName}"))
            .IgnoreAllPropertiesWithAnInaccessibleSetter();
    }
}
// 方式2：静态配置（适用于简单场景）
var config = new MapperConfiguration(cfg => {
    cfg.CreateMap<Order, OrderDto>();
});

3. 执行映射操作

// 通过依赖注入获取IMapper
public class OrderService
{
    private readonly IMapper _mapper;
    public OrderService(IMapper mapper)
    {
        _mapper = mapper;
    }
    public OrderDto GetOrder(int id)
    {
        var order = _repository.GetById(id);
        return _mapper.Map<OrderDto>(order);
    }
}
// 或直接使用Mapper实例
var config = new MapperConfiguration(cfg => cfg.CreateMap<Product, ProductViewModel>());
var mapper = config.CreateMapper();
var viewModel = mapper.Map<ProductViewModel>(product);

三、高级映射技巧

1. 复杂类型处理

// 嵌套对象映射
CreateMap<Customer, CustomerDto>()
    .ForMember(dest => dest.Address, opt => opt.MapFrom(src => src.ShippingAddress));
// 集合映射
CreateMap<List<Product>, List<ProductSummary>>();
// 或使用泛型
CreateMap<IEnumerable<Order>, IEnumerable<OrderLite>>();

2. 自定义值解析器

public class DateFormatterResolver : IValueResolver<Source, Destination, string>
{
    public string Resolve(Source source, Destination destination, string destMember, ResolutionContext context)
    {
        return source.CreateDate.ToString("yyyy-MM-dd");
    }
}
// 在Profile中注册
CreateMap<Source, Destination>()
    .ForMember(dest => dest.FormattedDate, opt => opt.MapFrom<DateFormatterResolver>());

3. 条件映射

CreateMap<Employee, EmployeeDto>()
    .ForMember(dest => dest.Bonus, opt => opt.Condition(src => src.PerformanceRating > 8));

4. 反向映射配置

CreateMap<Order, OrderDto>().ReverseMap();
// 或定制反向映射
CreateMap<OrderDto, Order>()
    .ForMember(dest => dest.Id, opt => opt.Ignore());

四、性能优化策略

1. 预编译映射

// 应用程序启动时编译
var config = new MapperConfiguration(cfg => {
    cfg.AddProfile<MappingProfile>();
});
config.AssertConfigurationIsValid(); // 验证配置
// 使用编译后的映射
var mapper = config.CreateMapper();

2. 缓存机制

AutoMapper默认使用ConcurrentDictionary缓存映射计划，在以下场景建议手动管理：

• 高频短生命周期对象映射
• 动态生成的映射配置

3. 批量映射优化

// 映射集合时避免循环引用
var orders = repository.GetAll();
var dtos = mapper.Map<List<OrderDto>>(orders);
// 大数据量分批处理
const int batchSize = 1000;
var total = sourceCollection.Count;
for (int i = 0; i < total; i += batchSize)
{
    var batch = sourceCollection.Skip(i).Take(batchSize);
    var batchResult = mapper.Map<List<Destination>>(batch);
    // 处理批次结果
}

五、最佳实践与避坑指南

1. 配置验证

// 启动时验证所有映射配置
var config = new MapperConfiguration(cfg => {
    cfg.AddProfile<ApplicationProfile>();
});
try
{
    config.AssertConfigurationIsValid();
}
catch (AutoMapperConfigurationException ex)
{
    // 处理配置错误
}

2. 常见问题解决方案

• 属性未映射错误：检查ForMember配置或使用Ignore()
• 循环引用：配置.MaxDepth(1)或使用DTO剪枝
• 性能瓶颈：避免在映射逻辑中执行数据库查询

3. 单元测试建议

[Test]
public void Should_Correctly_Map_Customer_To_Dto()
{
    var config = new MapperConfiguration(cfg => cfg.AddProfile<CustomerProfile>());
    var mapper = config.CreateMapper();
    var source = new Customer { Id = 1, Name = "Test" };
    var result = mapper.Map<CustomerDto>(source);
    Assert.AreEqual(source.Id, result.Id);
    Assert.AreEqual(source.Name, result.Name);
}

六、与依赖注入框架集成

1. ASP.NET Core集成

// Startup.cs
public void ConfigureServices(IServiceCollection services)
{
    services.AddAutoMapper(typeof(Startup));
    // 其他服务配置...
}

2. 自定义配置加载

public class AutoMapperInitializer
{
    public static MapperConfiguration Initialize()
    {
        var profiles = GetAllProfiles(); // 实现自定义Profile加载逻辑
        return new MapperConfiguration(cfg => {
            foreach (var profile in profiles)
            {
                cfg.AddProfile(profile);
            }
        });
    }
}

七、版本兼容性说明

AutoMapper版本	.NET支持范围	推荐使用场景
10.x	.NET Standard 2.0	传统ASP.NET Core 3.1项目
11.x	.NET 6/7	现代跨平台应用
12.x (预览)	.NET 8	最新技术栈

注意：升级到新版本时，需检查ReverseMap和AfterMap等API的变更，建议通过单元测试验证关键映射逻辑。

八、扩展生态介绍

1. AutoMapper.Collection：支持集合等价性比较
2. AutoMapper.Extensions.ExpressionMapping：LINQ表达式转换
3. AutoMapper.Contrib：社区贡献的扩展方法集

安装示例：

Install-Package AutoMapper.Collection

九、完整工作流示例

// 1. 定义模型
public class Product {
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
}
public class ProductDto {
    public int Id { get; set; }
    public string DisplayName { get; set; }
    public string FormattedPrice { get; set; }
}
// 2. 创建映射配置
public class ProductProfile : Profile
{
    public ProductProfile()
    {
        CreateMap<Product, ProductDto>()
            .ForMember(dest => dest.DisplayName, opt => opt.MapFrom(src => src.Name.ToUpper()))
            .ForMember(dest => dest.FormattedPrice, opt => opt.MapFrom(src => $"${src.Price:F2}"));
    }
}
// 3. 在服务中使用
public class ProductService
{
    private readonly IMapper _mapper;
    public ProductService(IMapper mapper) => _mapper = mapper;
    public IEnumerable<ProductDto> GetProducts()
    {
        var products = _repository.GetAll(); // 假设从数据库获取
        return _mapper.Map<IEnumerable<ProductDto>>(products);
    }
}

通过系统掌握上述内容，开发者可以构建出高效、可维护的对象映射解决方案。建议结合具体项目需求，从简单映射开始逐步引入高级特性，同时建立完善的单元测试体系确保映射正确性。