Mapperly 4.0版本的重要变更与升级指南

Mapperly作为.NET生态中高效的代码生成映射工具，即将迎来4.0版本的重大更新。本次更新包含多项重要变更，这些变更将显著影响现有代码库的兼容性，开发者需要提前了解并做好升级准备。

严格映射检查成为默认行为

4.0版本最核心的变更是将严格映射检查设为默认行为。具体体现在以下诊断规则的默认级别调整：

• 源成员未找到对应目标成员（RMG012）的默认级别调整为警告
• 源成员未映射到任何目标成员（RMG020）的默认级别调整为警告
• 源枚举成员未找到（RMG037）的默认级别调整为警告
• 目标枚举成员未找到（RMG038）的默认级别调整为警告

这项变更意味着Mapperly将更严格地检查映射配置的完整性，有助于在开发早期发现潜在的映射问题。对于现有项目，如果启用了"将警告视为错误"的编译选项，可能需要调整相关配置以避免编译失败。

枚举底层类型转换规则的优化

4.0版本改进了枚举底层类型的转换检查机制，从原来的显式转换（ExplicitCast）调整为专门的枚举底层类型转换（EnumUnderlayingType）。这一变更使得枚举类型间的映射更加精确和安全，特别是在处理不同基础类型（如int与long）的枚举转换时，能提供更合理的类型检查。

API设计的合理化调整

Mapperly 4.0对MapPropertyAttribute构造函数进行了重构，移除了同时接受两个字符串数组的构造函数重载，改为分别提供只接受源路径或目标路径的构造函数。这一变更使得API设计更加明确，避免了可能出现的混淆使用情况。

其他重要变更

虽然部分计划中的变更（如自动用户映射的默认值调整、无参构造函数的偏好设置等）最终未被纳入4.0版本，但开发者仍需注意：

• 多个用户映射发现未指定显式默认值的诊断规则（RMG060）的默认级别将调整为错误
• 整体上Mapperly将趋向于更严格和显式的映射配置方式

升级建议

对于计划升级到Mapperly 4.0的开发者，建议：

1. 提前在开发环境中测试新版本
2. 检查现有代码中的映射配置是否满足新的严格检查要求
3. 根据项目需要调整相关诊断规则的严重级别
4. 特别注意枚举类型映射的兼容性检查

这些变更虽然可能带来短期的适配工作，但从长远来看将提升代码的健壮性和可维护性，是Mapperly向更成熟、更可靠方向迈进的重要一步。