Sparkdo.Mapperly 1.0.2-preview.1

Sparkdo.Mapperly

Sparkdo Mapperly 集成库，提供基于 Mapperly 的对象映射功能实现。

功能特性

• 基于 Mapperly 的高性能对象映射
• 支持单向和双向映射
• 支持映射前后的钩子方法
• 支持额外属性映射
• 与 Sparkdo 框架无缝集成
• 支持依赖注入

安装

<PackageReference Include="Sparkdo.Mapperly" Version="x.x.x" />

核心组件

ISparkdoMapperlyMapper

基于 Mapperly 的对象映射器接口，用于将源对象映射到目标对象：

• Map(TSource source): 将源对象映射到新目标对象
• Map(TSource source, TDestination destination): 将源对象映射到现有目标对象
• BeforeMap(TSource source): 映射前钩子方法
• AfterMap(TSource source, TDestination destination): 映射后钩子方法

ISparkdoReverseMapperlyMapper

支持双向映射的 Mapperly 映射器接口，继承自 ISparkdoMapperlyMapper：

• ReverseMap(TDestination destination): 将目标对象映射到新源对象
• ReverseMap(TDestination destination, TSource source): 将目标对象映射到现有源对象
• BeforeReverseMap(TDestination destination): 反向映射前钩子方法
• AfterReverseMap(TDestination destination, TSource source): 反向映射后钩子方法

MapperBase

Mapperly 映射器的抽象基类，提供基本的映射功能实现：

• 实现了 ISparkdoMapperlyMapper 接口
• 提供了映射前后的虚拟钩子方法
• 使用瞬态生命周期注册到依赖注入容器中

TwoWayMapperBase

支持双向映射的 Mapperly 映射器抽象基类，继承自 MapperBase：

• 实现了 ISparkdoReverseMapperlyMapper 接口
• 提供了反向映射前后的虚拟钩子方法

MapExtraPropertiesAttribute

用于标记 Mapperly 映射器类，指示在映射过程中应处理额外属性：

• DefinitionChecks: 映射属性定义检查选项
• IgnoredProperties: 在映射过程中应忽略的额外属性名称数组
• MapToRegularProperties: 是否将额外属性映射到目标对象的常规属性

使用示例

定义映射器

public class UserProfileMapper : MapperBase<User, UserProfileDto>
{
    public override UserProfileDto Map(User source)
    {
        return new UserProfileDto
        {
            Id = source.Id,
            Name = source.Name,
            Email = source.Email
        };
    }

    public override void Map(User source, UserProfileDto destination)
    {
        destination.Id = source.Id;
        destination.Name = source.Name;
        destination.Email = source.Email;
    }

    public override void BeforeMap(User source)
    {
        // 映射前的准备工作
    }

    public override void AfterMap(User source, UserProfileDto destination)
    {
        // 映射后的清理工作
    }
}

双向映射器

public class UserMapper : TwoWayMapperBase<User, UserDto>
{
    public override UserDto Map(User source)
    {
        return new UserDto
        {
            Id = source.Id,
            Name = source.Name,
            Email = source.Email
        };
    }

    public override void Map(User source, UserDto destination)
    {
        destination.Id = source.Id;
        destination.Name = source.Name;
        destination.Email = source.Email;
    }

    public override User ReverseMap(UserDto destination)
    {
        return new User
        {
            Id = destination.Id,
            Name = destination.Name,
            Email = destination.Email
        };
    }

    public override void ReverseMap(UserDto destination, User source)
    {
        source.Id = destination.Id;
        source.Name = destination.Name;
        source.Email = destination.Email;
    }
}

使用映射器

public class UserService
{
    private readonly IObjectMapper _objectMapper;

    public UserService(IObjectMapper objectMapper)
    {
        _objectMapper = objectMapper;
    }

    public UserProfileDto GetUserProfile(long userId)
    {
        var user = GetUserById(userId);
        return _objectMapper.Map<User, UserProfileDto>(user);
    }

    public void UpdateUser(UserDto userDto)
    {
        var user = GetUserById(userDto.Id);
        _objectMapper.Map(userDto, user);
        SaveUser(user);
    }
}

扩展性

该库提供了完整的 Mapperly 集成功能实现，可以通过以下方式扩展：

1. 继承 MapperBase<TSource, TDestination> 来实现自定义的单向映射逻辑
2. 继承 TwoWayMapperBase<TSource, TDestination> 来实现自定义的双向映射逻辑
3. 使用 MapExtraPropertiesAttribute 来控制额外属性的映射行为
4. 通过依赖注入注册自定义映射器

代码结构说明

本项目包含以下主要组件：

映射器接口

• ISparkdoMapperlyMapper: 基本映射器接口
• ISparkdoReverseMapperlyMapper: 双向映射器接口

映射器基类

• MapperBase: 单向映射器基类
• TwoWayMapperBase: 双向映射器基类

特性

• MapExtraPropertiesAttribute: 额外属性映射特性

模块配置

• SparkdoMapperlyModule: Sparkdo Mapperly 模块配置
• SparkdoAutoMapperServiceCollectionExtensions: 服务注册扩展方法

所有公共接口和类都添加了详细的 XML 文档注释，便于开发者理解和使用。