Mapperly 中 IQueryable 投影映射的深度解析

理解 Mapperly 的映射机制

Mapperly 是一个高效的 .NET 对象映射库，它通过编译时代码生成来实现高性能的对象转换。在复杂业务场景中，我们经常需要处理嵌套对象结构的映射，特别是在数据库查询结果到 DTO 的转换过程中。

典型场景分析

考虑一个汽车销售系统的数据模型：

public class Car
{
    public string Model { get; set; }
    public Manufacturer Manufacturer { get; set; }
}

public class Manufacturer
{
    public string Name { get; set; }
    public Factory Factory { get; set; }
}

public class Factory
{
    public string Location { get; set; }
}

public class CarDto
{
    public string Model { get; set; }
    public string ManufacturerName { get; set; }
    public string FactoryLocation { get; set; }
}

传统手动映射方式需要编写冗长的 Select 表达式：

cars.Select(car => new CarDto
{
    Model = car.Model,
    ManufacturerName = car.Manufacturer.Name,
    FactoryLocation = car.Manufacturer.Factory.Location
})

Mapperly 的优雅解决方案

通过合理设计映射方法，我们可以实现更简洁的解决方案：

1. 基础映射方法：定义核心的 IQueryable 投影方法

public static IQueryable<CarDto> ProjectToDto(IQueryable<Car> q);

2. 属性级自定义映射：使用特性标记需要特殊处理的属性

[MapPropertyFromSource(nameof(CarDto.ManufacturerName), Use = nameof(MapManufacturerName))]
[MapPropertyFromSource(nameof(CarDto.FactoryLocation), Use = nameof(MapFactoryLocation))]
private static CarDto MapCar(Car car);

3. 自定义映射逻辑：实现具体的属性转换逻辑

private static string MapManufacturerName(Car car)
    => car.Manufacturer.Name;

private static string MapFactoryLocation(Car car)
    => car.Manufacturer.Factory.Location;

技术实现原理

Mapperly 的智能之处在于：

1. 编译时分析：在编译阶段分析所有映射关系，生成最优化的转换代码
2. 方法组合：自动将离散的映射方法组合成完整的转换逻辑
3. IQueryable 支持：保持查询表达式树结构，确保 Entity Framework Core 等 ORM 能正确翻译为 SQL

最佳实践建议

1. 分离关注点：将复杂属性的映射逻辑提取到独立方法中
2. 命名一致性：保持映射方法命名清晰一致，便于维护
3. 性能考量：对于高频调用的映射，考虑使用缓存或更直接的表达式
4. 测试验证：确保生成的 SQL 查询符合预期，特别是嵌套属性的访问

常见误区与解决方案

开发者常犯的错误是直接在 IQueryable 投影方法上应用属性映射特性，正确做法应该是：

1. 错误方式：直接在 ProjectToDto 方法上使用 MapPropertyFromSource
2. 正确方式：在实体到 DTO 的映射方法上应用特性
3. 原理：IQueryable 本身不包含映射属性，需要在实体映射层面定义

通过这种模式，Mapperly 能够生成高效的、可被 ORM 正确翻译的查询表达式，同时保持代码的简洁性和可维护性。