Inkslab.Map 1.2.25

Inkslab.Map 是什么？

Inkslab.Map 是 IMapper 的默认实现——一个基于表达式树的约定优先对象映射器，适用于 DTO / 实体 / VM 之间的双向转换。

• 属性名忽略大小写自动匹配。
• 支持集合 / 数组 / Dictionary 映射。
• 支持构造函数映射（New）。
• 支持属性级自定义：Map、From、Constant、Ignore。
• 支持继承与包含映射：Include、Profile。
• 基于表达式树编译，安全映射非空类型间关系，无须处理 null/Nullable 分支。

与 AutoMapper 定位不同：本框架优先"安全对象深拷贝 + 自动匹配"，AutoMapper 优先"值转换 + 显式映射"。需要类似 AutoMapper 的表现，可禁用深拷贝配置。

安装

dotnet add package Inkslab.Map

安装后由 MStartup 自动注册 IMapper 默认实现。

快速入门

1. 自动映射

FooDto foo = Mapper.Map<FooDto>(fooEntity);
BarDto bar = Mapper.Map<BarDto>(barEntity);

2. 集合 / 数组 / 字典

var arr  = Mapper.Map<UserDto[]>(userArr);
var list = Mapper.Map<List<UserDto>>(users);
var dict = Mapper.Map<Dictionary<string, object>>(user);

3. 构造函数映射

目标类型具备匹配构造函数时自动选用：

public record B(int Id, string Name, DateTime CreatedAt);

var b = Mapper.Map<B>(a);

核心契约

IMapper src/Inkslab/Map/IMapper.cs

public interface IMapper
{
    T      Map<T>(object obj);
    object Map   (object obj, Type destinationType);
}

静态门面 Mapper src/Inkslab/Map/Mapper.cs

Mapper.Map<UserDto>(user);
Mapper.Map(user, typeof(UserDto));

默认实现 MapperInstance src/Inkslab.Map/MapperInstance.cs

继承 Profile，实例化后可在当前范围内配置定制规则（using 确保释放）。

using var instance = new MapperInstance();
instance.Map<From, To>()
        .Map(...);

var dto = instance.Map<To>(source);

进阶用法

1. 属性级自定义

using var instance = new MapperInstance();

instance.Map<C1, C2>()
    .Map(x => x.R1, y => y.From(z => z.P1))                    // 字段改名
    .Map(x => x.T3, y => y.From(z => z.P3.ToString()))         // 类型转换
    .Map(x => x.D4, y => y.Constant(DateTimeKind.Utc))         // 常量
    .Map(x => x.I5, y => y.Ignore());                          // 忽略属性

var dst = instance.Map<C2>(src);

2. 继承与包含

instance.Map<C2, C1>()
        .Include<C3>()                                         // 规则同时作用于 C2→C1 与 C2→C3
        .Map(x => x.P1, y => y.From(z => z.R1))
        .Map(x => x.P3, y => y.From(z => Convert.ToDateTime(z.T3)));

var c3 = instance.Map<C3>(src);

3. 构造函数自定义

instance.New<C1, C4>(x => new C4(x.P1))
        .Map(x => x.T3, y => y.From(z => z.P3.ToString()))
        .Map(x => x.D4, y => y.Constant(DateTimeKind.Utc))
        .Map(x => x.I5, y => y.Ignore());

4. 集合到集合的自定义构造

instance.Map<C1, C2>()
        .NewEnumerable<PagedList<C1>, PagedList<C2>>(
            (src, mapped) => new PagedList<C2>(mapped, src.PageIndex, src.PageSize, src.Total));

5. 使用 Profile 预定义规则

public class OrderProfile : Profile
{
    public OrderProfile()
    {
        Map<OrderEntity, OrderDto>()
            .Map(d => d.PayTime, o => o.From(s => s.PaidAt));
    }
}

// 向全局映射配置注册（必须在 Mapper.Map<T> 首次调用之前）：
MapConfiguration.Instance.AddProfile(new OrderProfile());
// 或按类型注册（内部自动实例化，要求有无参或参数均有默认值的构造函数）：
MapConfiguration.Instance.AddProfile(typeof(OrderProfile));

内置映射规则

默认实现内置多种常用规则（位于 src/Inkslab.Map/Maps/），按优先级匹配：

自定义实现

public class MyMapper : IMapper
{
    public T      Map<T>(object obj)                        => /* ... */;
    public object Map   (object obj, Type destinationType)  => /* ... */;
}

// 启动前替换
SingletonPools.TryAdd<IMapper, MyMapper>();

性能与注意事项

• 默认深拷贝：源引用不会被共享，避免后续修改误伤。
• 不支持循环引用：递归关系会抛出或导致栈溢出；请显式 Ignore 自引用。
• 复用 MapperInstance：批量映射时复用同一实例以命中表达式编译缓存。
• 线程安全：MapperInstance 的配置阶段非线程安全；应用（Map 调用）线程安全。

单元测试

• tests/Inkslab.Map.Tests/DefaultTests.cs：默认规则。
• tests/Inkslab.Map.Tests/CustomTests.cs：自定义规则。
• tests/Inkslab.Map.Tests/ProfileConcurrencyTests.cs：Profile 并发测试。
• tests/Inkslab.Map.Tests/ApplyTest.cs：应用示例。

说明

• 与 AutoMapper 的核心差异：
  • 本框架无需强制声明映射关系——未声明的属性按名称忽略大小写自动匹配。
  • 本框架支持集合到集合的自定义构造。
  • 本框架默认深拷贝，避免数据源被意外共享。
• 基于表达式树分析 + 组合实现映射，运行时零反射开销。