Mapperly 映射库中投影方法手动映射失效问题分析

问题概述

在使用Mapperly对象映射库时，发现了一个关于投影(Projection)方法中手动映射规则失效的问题。具体表现为：当为子模型定义手动映射规则时，该规则能够正确应用于顶级模型的投影操作；但当为顶级模型本身定义手动映射规则时，Mapperly却仍然尝试自动生成映射代码，导致预期的手动映射规则未被采用。

问题复现场景

考虑以下实体和模型定义：

// 实体类
public class User {
    public Guid Id { get; set; }
    public string Name { get; set; } = null!;
    public Address Address { get; set; } = null!;
}

public class Address {
    public Guid Id { get; set; }
    public string Street { get; set; } = null!;
}

// 模型类
public class UserModel {
    public Guid Id { get; set; }
    public string Name { get; set; } = null!;
    public AddressModel Address { get; set; } = null!;
}

public class AddressModel {
    public Guid id { get; set; }  // 注意大小写差异
    public string street { get; set; } = null!;
}

在映射配置中，我们为Address到AddressModel定义了手动映射规则：

[Mapper]
public static partial class TestMapper {
    public static partial IQueryable<UserModel> ProjectToUserModel(IQueryable<User> queryable);
    public static partial IQueryable<AddressModel> ProjectToAddressModel(IQueryable<Address> queryable);
    
    public static AddressModel AddressManualMapping(Address entity) => new AddressModel() {
        id = entity.Id,
        street = "asdf",  // 硬编码值用于测试
    };
}

预期与实际行为对比

预期行为：

1. 对于ProjectToUserModel方法，Mapperly应该识别到Address属性需要映射到AddressModel，并调用我们定义的AddressManualMapping方法
2. 对于ProjectToAddressModel方法，Mapperly应该直接使用我们定义的AddressManualMapping方法

实际行为：

1. ProjectToUserModel方法正确使用了手动映射规则
2. ProjectToAddressModel方法却忽略了手动映射规则，尝试自动生成映射代码

问题根源分析

经过分析，这个问题源于Mapperly在处理投影方法时的逻辑缺陷：

1. 对于嵌套模型的映射，Mapperly会优先查找用户定义的手动映射方法
2. 但对于顶级模型的映射，Mapperly在当前版本中似乎会跳过手动映射方法的检查流程
3. 当自动映射失败时（如本例中由于属性名大小写不匹配），Mapperly会生成一个空的对象初始化器而非回退到手动映射方法

解决方案与变通方法

虽然这是一个需要修复的bug，但在等待修复期间，可以考虑以下解决方案：

1. 显式指定映射方法：使用[MapperUseMapping]特性明确指定要使用的手动映射方法
2. 调整命名策略：如果问题仅源于大小写差异，可以配置Mapperly使用大小写不敏感的匹配策略
3. 临时解决方案：对于顶级模型投影，可以先调用Select手动应用映射规则

技术启示

这个问题提醒我们在使用对象映射库时需要注意：

1. 手动映射规则的应用范围可能因上下文而异
2. 自动映射失败时的回退行为需要特别关注
3. 对于复杂的映射场景，建议编写单元测试验证生成的映射代码是否符合预期

总结

Mapperly作为高效的编译时对象映射解决方案，在大多数情况下表现优异。这个特定的投影映射问题虽然影响有限（仅影响顶级模型的手动映射），但在某些场景下可能导致意外的行为。理解这一限制有助于开发者更好地规划映射策略，或者在遇到类似问题时能够快速定位原因。