Mapperly项目中的枚举映射增强：支持EnumMemberAttribute和DescriptionAttribute

在现代.NET应用程序开发中，枚举(Enum)类型经常需要与字符串进行相互转换，特别是在处理API序列化/反序列化、数据库存储或UI显示等场景时。Mapperly作为一个高效的.NET对象映射库，近期社区提出了增强其枚举映射功能的建议，特别是支持通过EnumMemberAttribute和DescriptionAttribute来定义枚举值的字符串表示形式。

当前枚举映射的局限性

Mapperly目前主要支持以下几种枚举映射方式：

1. 默认的成员名称映射（直接使用枚举成员名称）
2. 数值映射（使用枚举的底层数值）
3. 通过MapEnumValueAttribute自定义映射

然而，在实际开发中，开发者经常使用System.Runtime.Serialization.EnumMemberAttribute来定义枚举值的序列化名称，或者使用System.ComponentModel.DescriptionAttribute为枚举值提供描述性文本。这些标准.NET特性目前无法直接在Mapperly中使用。

使用场景分析

考虑以下典型场景：

[DataContract]
public enum TimeZone
{
    [EnumMember(Value = "Africa/Abidjan")] 
    AfricaAbidjan,
    [EnumMember(Value = "Africa/Algiers")] 
    AfricaAlgiers
}

开发者希望将"Africa/Abidjan"字符串直接映射到TimeZone.AfricaAbidjan枚举值，反之亦然。目前Mapperly不支持这种基于EnumMemberAttribute的映射，开发者不得不编写额外的转换代码。

技术实现方案

1. 配置方式

建议新增一个配置选项EnumNameSource，支持以下值：

• MemberName（默认）：使用枚举成员名称
• EnumMemberAttribute：使用EnumMemberAttribute.Value
• DescriptionAttribute：使用DescriptionAttribute.Description

示例配置：

[Mapper(EnumNameSource = EnumNameSource.EnumMemberAttribute)]
public partial class MyMapper
{
    // 映射逻辑
}

2. 处理重复值

当多个枚举成员具有相同的字符串表示时，需要特别处理：

• 如果重复值来自相同的字符串表示：忽略重复，使用第一个匹配项
• 如果重复值来自不同的字符串表示：编译时抛出错误

3. 性能考虑

由于Mapperly是源代码生成器，所有映射逻辑都在编译时确定，因此使用特性标记不会带来运行时反射开销。

与现有功能的对比

现有MapEnumValueAttribute功能与EnumMemberAttribute功能相似，但各有优势：

• MapEnumValueAttribute：更灵活，可以在映射类中集中定义
• EnumMemberAttribute：更标准，与.NET生态系统更兼容

兼容性考虑

为了保持向后兼容，新功能应默认禁用，开发者需要显式启用。在未来的主要版本更新中，可以考虑改变默认行为。

实际应用示例

启用EnumMemberAttribute支持后，映射代码将变得非常简洁：

[Mapper(EnumNameSource = EnumNameSource.EnumMemberAttribute)]
public partial class TimeZoneMapper
{
    public partial string ToString(TimeZone value);
    public partial TimeZone ToTimeZone(string value);
}

生成的代码将自动处理EnumMemberAttribute中定义的字符串表示。

未来展望

随着.NET 9对AOT编译的改进，EnumMemberAttribute的支持将变得更加重要。这个增强功能将使Mapperly在更多场景下成为处理枚举映射的首选工具。

对于开发者来说，这一改进将显著简化涉及枚举与字符串转换的代码，提高开发效率，同时保持类型安全和性能优势。