Mapperly项目中的自定义映射方法选择功能解析

背景介绍

在现代软件开发中，对象映射是一个常见需求，特别是在不同层之间传输数据时。Mapperly作为一个高效的.NET对象映射库，提供了强大的代码生成能力。在实际应用中，开发者经常会遇到需要自定义映射逻辑的情况，特别是当源类型和目标类型相同但需要不同处理方式时。

问题场景

考虑以下典型场景：我们需要将DateTime类型映射到long类型，但根据业务需求，有时需要转换为秒级时间戳，有时需要毫秒级时间戳。例如：

private static long DateTimeToUnixTimeSeconds(DateTime source)
{
   return source.ToUnixTimeSeconds();
}

private static long DateTimeToUnixTimeMilliseconds(DateTime source)
{
   return source.ToUnixTimeMilliseconds();
}

这两个方法具有完全相同的签名（DateTime→long），但执行不同的转换逻辑。传统方式下，Mapperly无法区分应该使用哪个方法。

解决方案

Mapperly通过增强MapProperty属性解决了这个问题。新版本允许开发者在属性映射中显式指定要使用的转换方法名称：

[MapProperty(
    nameof(DeliveryRate.EndDateTimeUtc), 
    nameof(DeliveryRateResponse.EndDateTimeUnixOffsetMilliseconds), 
    Conversion = nameof(DateTimeToUnixTimeMilliseconds)
]

这种设计使得开发者可以：

1. 保持类型安全
2. 明确指定转换逻辑
3. 避免歧义
4. 生成更精确的映射代码

实际应用案例

另一个常见应用场景是处理DateTime的Kind属性。从数据库查询得到的DateTime通常具有Unspecified的Kind，而在服务契约中需要明确指定为UTC：

[MapProperty(
    nameof(DeliveryRate.StartDateTimeUtc), 
    nameof(DeliveryRateResponse.StartDateTimeUtc), 
    Conversion = nameof(DateTimeToDateTimeUtc))
]

对应的转换方法可能是：

private static DateTime DateTimeToDateTimeUtc(DateTime source)
{
    return DateTime.SpecifyKind(source, DateTimeKind.Utc);
}

技术实现原理

Mapperly在代码生成阶段会：

1. 分析所有标记了MapProperty的属性
2. 检查是否指定了Conversion参数
3. 验证指定的方法是否存在且签名匹配
4. 生成直接调用指定方法的代码

这种方式相比反射或表达式树具有更好的性能和编译时安全性。

最佳实践建议

1. 为常用转换创建专门的静态方法类
2. 方法命名应清晰表达转换意图
3. 保持转换方法的纯粹性（无副作用）
4. 对于复杂转换，考虑使用多个简单方法的组合

总结

Mapperly的自定义映射方法选择功能为开发者提供了更精细的控制能力，特别是在处理相同类型但需要不同转换逻辑的场景下。这种设计既保持了Mapperly原有的简洁性，又增加了必要的灵活性，是对象映射库设计中的一个优雅解决方案。