序言

在日常编程活动中，我们经常需要将一个对象映射至另一对象，例如将数据库实体转换成数据传输对象（DTO），或者将请求模型映射为领域模型。这一过程通常包含大量重复代码，如果每次都手动编写，不仅会极大降低开发效率，而且随着项目的扩展，还容易产生错误（如：属性遗漏、手写错误或复制粘贴失误等）。

本文的主要内容是介绍如何在 ASP.NET Core 9.0 Web API 项目中利用 Mapster 实现快速且高效的对象映射。

Mapster 概述

Mapster 是一款开源免费（MIT 许可证）、迅速、高性能、灵活且便于使用的 .NET 对象映射库，旨在简化 .NET 应用程序中对象间转换和映射的操作，显著减少因手动赋值导致的重复代码、人为错误和维护成本。

安装 Mapster 相关包

方法一、通过 NuGet 包管理器安装

在 NuGet 包管理器中查找并安装：Mapster 和 Mapster.DependencyInjection：

• Mapster - 核心功能包
[此处为图片1]
• Mapster.DependencyInjection - 依赖注入集成包
[此处为图片1]

方法二、通过 .NET CLI 安装

dotnet add package Mapster --version 7.4.0 #核心功能包
dotnet add package Mapster.DependencyInjection --version 1.0.1 #依赖注入集成包

在 Program.cs 中注册 Mapster 服务

var builder = WebApplication.CreateBuilder(args);
// 注册 Mapster 服务
builder.Services.AddMapster();
// 注册 Mapster 映射规则
MapsterConfig.Register();

基础映射一行代码完成

接下来我们将分别定义一个源对象（Student）和一个目标对象（StudentViewModel），它们的属性名称和类型完全相同。

Student（源对象）

public class Student
{
    /// <summary>
    /// 学生ID [主键，自动递增]
    /// </summary>
    [PrimaryKey, AutoIncrement]
    [Display(Name = "学生ID")]
    public int StudentID { get; set; }

    /// <summary>
    /// 班级ID
    /// </summary>
    [Display(Name = "班级ID")]
    public int ClassID { get; set; }

    /// <summary>
    /// 学生姓名
    /// </summary>
    [Display(Name = "学生姓名")]
    public string Name { get; set; }

    /// <summary>
    /// 学生年龄
    /// </summary>
    [Display(Name = "学生年龄")]
    public int Age { get; set; }

    /// <summary>
    /// 学生性别
    /// </summary>
    [Display(Name = "学生性别")]
    public string Gender { get; set; }
}

StudentViewModel（目标对象）

public class StudentViewModel
{
    /// <summary>
    /// 学生ID
    /// </summary>
    [PrimaryKey, AutoIncrement]
    [Display(Name = "学生ID")]
    public int StudentID { get; set; }

    /// <summary>
    /// 班级ID
    /// </summary>
    [Display(Name = "班级ID")]
    public int ClassID { get; set; }

    /// <summary>
    /// 学生姓名
    /// </summary>
    [Display(Name = "学生姓名")]
    public string Name { get; set; }

    /// <summary>
    /// 学生年龄
    /// </summary>
    [Display(Name = "学生年龄")]
    public int Age { get; set; }

    /// <summary>
    /// 学生性别
    /// </summary>
    [Display(Name = "学生性别")]
    public string Gender { get; set; }

    /// <summary>
    /// 班级名称
    /// </summary>
    [Display(Name = "班级名称")]
    public string ClassName { get; set; }
}

当属性名称和类型相匹配时，Mapster 能够自动完成映射，无需任何额外配置！

private async Task<List<StudentViewModel>> GetStudentClassInfo(List<Student> students)
{
    // Mapster 映射（无需任何配置！）
    var result = students.Adapt<List<StudentViewModel>>();
    return result;
}

        var studentsListDto = students.Adapt>();
        if (studentsListDto?.Count > 0)
        {
            var classIDs = studentsListDto.Select(x => x.ClassID).Distinct().ToList();
            var querySchoolClassList = await _schoolClassHelper.QueryAsync(x => classIDs.Contains(x.ClassID)).ConfigureAwait(false);
            if (querySchoolClassList?.Count > 0)
            {
                foreach (var studentItem in studentsListDto)
                {
                    var getClassInfo = querySchoolClassList.FirstOrDefault(x => x.ClassID == studentItem.ClassID);
                    if (getClassInfo != null)
                    {
                        studentItem.ClassName = getClassInfo.ClassName;
                    }
                }
            }
        }
        return studentsListDto;
    

映射结果输出：

自定义映射规则

当属性名称或类型不匹配时，可以通过配置指明映射逻辑。

UserInfo（源对象）

        public class UserInfo
        {
            public int Id { get; set; }
            public string FirstName { get; set; }
            public string LastName { get; set; }
            public string Email { get; set; }
            public DateTime CreatedAt { get; set; }
        }
    

UserInfoViewModel（目标对象）

        public class UserInfoViewModel
        {
            public int Id { get; set; }
            /// <summary>
            /// 合并 FirstName + LastName
            /// </summary>
            public string FullName { get; set; }
            public string Email { get; set; }
            /// <summary>
            /// 格式化日期
            /// </summary>
            public string CreatedDate { get; set; }
        }
    

配置 Mapster 映射规则

在项目的根目录创建 MapsterConfig.cs 文件：

        /// <summary>
        /// Mapster 全局映射配置类。
        /// 用于集中注册项目中所有的自定义对象映射规则，
        /// 避免映射逻辑分散，提高可维护性和可测试性。
        /// </summary>
        public static class MapsterConfig
        {
            /// <summary>
            /// 注册所有的自定义 Mapster 映射配置
            /// 此方法应仅在应用程序启动时（例如在 Program.cs 中）调用一次
            /// </summary>
            public static void Register()
            {
                TypeAdapterConfig
                    .NewConfig()
                    .Map(dest => dest.FullName,
                         src => $"{src.FirstName} {src.LastName}".Trim())
                    .Map(dest => dest.CreatedDate,
                         src => src.CreatedAt.ToString("yyyy-MM-dd"));
            }
        }
    

自定义映射规则

        /// <summary>
        /// 使用 Mapster 映射 UserInfo 的示例
        /// </summary>
        [ApiController]
        [Route("api/[controller]/[action]")]
        public class UserInfoController : ControllerBase
        {
            private readonly IMapper _mapper;
            /// <summary>
            /// 依赖注入
            /// </summary>
            /// <param name="mapper">映射器</param>
            public UserInfoController(IMapper mapper)
            {
                _mapper = mapper;
            }
            /// <summary>
            /// 获取用户信息
            /// </summary>
            [HttpGet]
            public List<UserInfoViewModel> GetUserInfos()
            {
                var userInfos = new List<UserInfo>
                {
                    new UserInfo
                    {
                        Id = 999,
                        FirstName = "李",
                        LastName = "四",
                        Email = "lisi@qq.com",
                        CreatedAt = DateTime.Now.AddYears(-5)
                    },
                    new UserInfo
                    {
                        Id = 666,
                        FirstName = "张",
                        LastName = "三",
    

Email = "zhangsan@example.com",
CreatedTime = DateTime.UtcNow.AddDays(-10)
}
};
// 利用 Mapster 进行映射
var getUserInfoViewModels = _mapper.Map<(userInfos);
return getUserInfoViewModels;
}
}
映射结果输出：
[此处为图片1]
完整示例源代码
https://github.com/YSGStudyHards/EasySQLite
[此处为图片2]