Mapster C# (.NET) 完全指南：安装、方法与实战示例

Mapster 是 .NET 生态中一款高性能的对象映射（object-to-object mapping）库。它能自动将一个类型的对象转换为另一个类型，让开发者告别繁琐的属性复制代码。与 AutoMapper 等重量级工具相比，Mapster 更注重运行速度和低内存占用，这一点已得到众多基准测试的验证。

为什么需要对象映射？在实际项目中，我们经常需要转换数据：DTO（数据传输对象）转 Entity、ViewModel 转 Model、Model 转 Response 等等。手动逐个字段复制不仅枯燥、容易出错，还会增加代码维护成本。Mapster 通过提供简单、灵活且快速的 API 来自动完成映射，完美解决这一问题。

Mapster 在编译阶段（通过 Roslyn 分析器）或使用动态表达式编译来生成映射代码。这使得它成为 .NET 中最快的映射工具之一，在某些场景下甚至比手动复制还要快。该库支持复杂场景：嵌套对象、集合、条件映射、字段忽略、不同类型适配器等等。

安装

通过 NuGet 包管理器安装 Mapster。在包管理器控制台中执行以下任一命令：

dotnet add package Mapster

或者通过包管理器控制台：

Install-Package Mapster

如果需要在 ASP.NET Core 中使用依赖注入（DI），建议额外安装以下包：

dotnet add package Mapster.DependencyInjection

安装完成后，在代码文件开头添加 using Mapster;。

快速上手

来看一个最简单的示例：我们有一个 User 类（数据库模型）和一个 UserDto 类（用于客户端传输）。

using Mapster;

// 源类
public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
    public DateTime CreatedAt { get; set; }
}

// 目标类
public class UserDto
{
    public int Id { get; set; }
    public string FullName { get; set; }
    public string Email { get; set; }
}

// 使用示例
public class Program
{
    public static void Main()
    {
        var user = new User
        {
            Id = 1,
            Name = "张三",
            Email = "zhangsan@example.com",
            CreatedAt = DateTime.Now
        };

        // 使用 Mapster 进行映射
        var dto = user.Adapt<UserDto>();

        Console.WriteLine($"Id: {dto.Id}, 姓名: {dto.FullName}, 邮箱: {dto.Email}");
        // 输出: Id: 1, 姓名: 张三, 邮箱: zhangsan@example.com
    }
}

注意：属性 Name 自动映射到了 FullName，因为 Mapster 默认会按名称（不区分大小写）尝试匹配。如果 UserDto 中也有 Name 属性，同样会被映射。

核心方法与类

下面介绍 Mapster 的关键方法。每个方法都包含签名、说明和示例。

1. Adapt<TDestination>(object source)

签名： public static TDestination Adapt<TDestination>(this object source)

说明： 最基本的扩展方法，用于将一个对象映射到另一个类型。它会创建 TDestination 的新实例，并从 source 复制属性值。

var user = new User { Id = 1, Name = "李四" };
var dto = user.Adapt<UserDto>();
Console.WriteLine(dto.FullName); // 输出: 李四