Mapperly项目中的对象合并功能解析与问题修复

Mapperly作为一个高效的.NET对象映射库，提供了强大的对象转换功能。其中对象合并(Merge Objects)是一个实用特性，允许开发者将源对象的属性值合并到目标对象中。

对象合并功能原理

Mapperly的对象合并功能通过扩展方法实现，其核心思想是：

1. 将源对象(source)的属性值复制到目标对象(target)
2. 仅当源对象属性值不为null时才会覆盖目标对象属性
3. 通过静态扩展方法提供流畅的API调用体验

典型使用场景

对象合并特别适用于以下场景：

• 部分更新对象属性
• 合并来自不同来源的数据
• 实现类似补丁更新的功能
• 避免全量更新时的null值覆盖问题

问题发现与修复

在Mapperly 3.4.0版本中，用户报告了一个关于对象合并功能失效的问题。经过分析发现：

1. 问题表现：生成的合并方法体为空，未执行任何属性复制操作
2. 根本原因：方法参数顺序不正确，Mapperly要求源对象必须是第一个参数
3. 修复方案：调整参数顺序，确保源对象在前

正确使用方法

以下是修正后的正确使用示例：

// 定义实体类
class Fruit { 
    public required string Name { get; set; } 
    public required string Color { get; set; } 
}

// 定义更新DTO
record FruitUpdate(string? Name, string? Color);

// 配置Mapper
[Mapper(AllowNullPropertyAssignment = false)]
static partial class FruitMapper
{
    public static partial void ApplyUpdate(this FruitUpdate update, Fruit fruit);
}

// 使用示例
var fruit = new Fruit() { Color = "Green", Name = "Apple" };
var fruitForUpdate = new FruitUpdate("Red", null);
fruitForUpdate.ApplyUpdate(fruit);

注意事项

1. 参数顺序必须正确：源对象在前，目标对象在后
2. 可以通过AllowNullPropertyAssignment控制null值处理行为
3. 合并操作不会影响目标对象中源对象为null的属性
4. 建议使用record类型作为更新源，因其天然支持不可变性和nullability

版本更新

此问题已在Mapperly 3.5.0-next.4版本中修复。开发者应确保使用正确的方法签名以获得预期的合并行为。