Mapperly中Create方法自动映射问题解析与解决方案

问题背景

在使用对象映射工具Mapperly时，开发者可能会遇到一个特殊场景：当目标类型中存在名为Create的方法时，Mapperly会优先使用这个方法进行映射，而不是按照预期生成属性映射代码。这种行为在Mapperly 4.2.0版本中引入，与早期版本(如3.5.1)的行为有所不同。

典型问题场景

考虑以下业务场景：我们有一个TrainingDoc实体类和一个继承自它的TrainingDoc_ForDisplay展示模型类。展示模型类中定义了两个静态Create方法用于转换：

public class TrainingDoc_ForDisplay : TrainingDoc
{
    public int Id => TrainingDocId;
    public string DocumentTypeName { get; set; } = "";
    
    public static TrainingDoc_ForDisplay Create(TrainingDoc trainingDoc)
    {
        var item = GraphQLMapperly.Map(trainingDoc);
        item.DocumentTypeName = EnumHelper<TrainingDocumentType>.GetDisplayValue(trainingDoc.DocumentType);
        return item;
    }
    
    [UserMapping(Ignore = true)]
    public static List<TrainingDoc_ForDisplay> Create(List<TrainingDoc> trainingDocs)
    {
        return trainingDocs.Select(t => Create(t)).ToList();
    }
}

问题表现

在Mapperly 4.2.0版本中，生成的映射代码会直接调用Create方法：

public static partial TrainingDoc_ForDisplay Map(TrainingDoc doc)
{
    return TrainingDoc_ForDisplay.Create(doc);
}

这导致了严重的循环引用问题，因为Create方法内部又调用了GraphQLMapperly.Map，最终引发堆栈溢出。

问题根源

此行为源于Mapperly 4.2.0引入的自动转换方法检测功能。Mapperly会：

1. 自动检测目标类型中是否存在合适的转换方法
2. 优先使用这些方法而不是生成属性映射代码
3. 特别关注名为Create的方法，将其视为对象工厂方法

解决方案

方案一：禁用静态转换方法

最直接的解决方案是在Mapperly配置中禁用静态转换方法的自动检测：

[Mapper(EnabledConversions = MappingConversionType.All & ~MappingConversionType.StaticConvertMethods)]
public partial class MyMapper
{
    // 映射配置
}

这样配置后，Mapperly将不再自动使用类中的静态Create方法，而是会生成显式的属性映射代码。

方案二：重命名方法

如果不希望修改全局配置，也可以选择重命名方法，避免使用Create这个特定名称：

public static TrainingDoc_ForDisplay MakeFrom(TrainingDoc trainingDoc)
{
    // 方法实现
}

方案三：显式忽略特定方法

虽然[UserMapping(Ignore = true)]在这个场景下没有生效，但可以尝试其他Mapperly提供的忽略机制：

[MapperIgnore]
public static TrainingDoc_ForDisplay Create(TrainingDoc trainingDoc)
{
    // 方法实现
}

最佳实践建议

1. 版本升级注意：从Mapperly 3.x升级到4.x时，应特别注意自动转换行为的变化
2. 命名规范：避免在DTO类中使用Create等可能被映射框架识别为特殊用途的方法名
3. 循环引用检查：在设计映射方法时，注意避免潜在的循环引用
4. 测试覆盖：对映射逻辑增加单元测试，特别是涉及自定义转换方法的场景

总结

Mapperly作为高效的编译时映射工具，其自动方法检测功能虽然强大，但在特定场景下可能导致意外行为。通过理解其工作原理和配置选项，开发者可以灵活控制映射行为，避免类似问题发生。在遇到类似问题时，优先考虑通过配置而非代码修改来解决问题，以保持代码的整洁性和一致性。