脚本之家 服务器常用软件
快捷导航
您的位置：首页 → 软件编程 → java → Java MapStruct

Java中基于注解的代码生成工具MapStruct映射使用详解

 更新时间：2025年02月10日 09:04:49   作者：Andya  
MapStruct 作为一个基于注解的代码生成工具,为我们提供了一种更加优雅、高效的解决方案,本文主要为大家介绍了它的具体使用,感兴趣的可以了解下

介绍

在 Java 开发中，我们经常需要在不同的 Java Bean 之间进行数据映射，比如从实体类（Entity）到数据传输对象（DTO）的转换。传统的做法是手动编写大量的 setter 和 getter 方法来完成属性的赋值，这种方式不仅繁琐，而且容易出错。MapStruct 作为一个基于注解的代码生成工具，为我们提供了一种更加优雅、高效的解决方案。它在编译时自动生成映射代码，避免了运行时反射带来的性能开销，同时保证了类型安全。

优缺点

优点

  • 高性能：MapStruct 在编译阶段生成映射代码，运行时直接调用这些代码，避免了反射的使用，从而显著提高了性能。
  • 类型安全：由于映射代码是在编译时生成的，编译器会对类型进行检查，因此可以在编译阶段发现类型不匹配等错误，避免了运行时异常。
  • 代码简洁：使用 MapStruct 只需要定义映射接口和使用注解进行配置，无需手动编写大量的映射逻辑，大大减少了代码量，提高了开发效率。

缺点

  • 学习成本：需要学习 MapStruct 提供的各种注解及其使用方法，对于初学者来说可能有一定的学习曲线。
  • 依赖管理：需要在项目中引入 MapStruct 的相关依赖，增加了项目的依赖管理复杂度。

核心注解及详细使用语法说明

@Mapper

  • 作用：用于标记一个接口为映射接口，MapStruct 会在编译时为该接口生成具体的实现类。
  • 使用语法：
import org.mapstruct.Mapper;
import org.mapstruct.factory.Mappers;

@Mapper
public interface UserMapper {
    // 通过 Mappers.getMapper 方法获取映射接口的实例
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);

    // 定义从 UserEntity 到 UserDTO 的映射方法
    UserDTO toDTO(UserEntity entity);
    // 定义从 UserDTO 到 UserEntity 的映射方法
    UserEntity toEntity(UserDTO dto);
}

@Mapping

  • 作用：用于指定源对象和目标对象之间的属性映射关系，当源对象和目标对象的属性名不一致时，可以使用该注解进行显式映射。
  • 使用语法：
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.factory.Mappers;

@Mapper
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);

    // 使用 @Mapping 注解指定 entityId 映射到 id，entityName 映射到 name
    @Mapping(source = "entityId", target = "id")
    @Mapping(source = "entityName", target = "name")
    UserDTO toDTO(UserEntity entity);

    // 反向映射
    @Mapping(source = "id", target = "entityId")
    @Mapping(source = "name", target = "entityName")
    UserEntity toEntity(UserDTO dto);
}

@Mappings

  • 作用：@Mappings 是 @Mapping 的集合形式，用于一次性指定多个属性映射关系。
  • 使用语法：
import org.mapstruct.Mapper;
import org.mapstruct.Mappings;
import org.mapstruct.Mapping;
import org.mapstruct.factory.Mappers;

@Mapper
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);

    @Mappings({
        @Mapping(source = "entityId", target = "id"),
        @Mapping(source = "entityName", target = "name")
    })
    UserDTO toDTO(UserEntity entity);

    @Mappings({
        @Mapping(source = "id", target = "entityId"),
        @Mapping(source = "name", target = "entityName")
    })
    UserEntity toEntity(UserDTO dto);
}

@Context

  • 作用：用于在映射过程中传递上下文信息，比如一些辅助对象，这些对象可以在映射方法中使用。
  • 使用语法：
import org.mapstruct.Mapper;
import org.mapstruct.Context;
import org.mapstruct.factory.Mappers;
import java.util.Locale;

@Mapper
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);

    // 使用 @Context 注解传递 Locale 对象作为上下文信息
    UserDTO toDTO(UserEntity entity, @Context Locale locale);
}

@AfterMapping

  • 作用：用于在映射完成后执行自定义的逻辑，比如对目标对象的某些属性进行额外的处理。
  • 使用语法：
import org.mapstruct.Mapper;
import org.mapstruct.AfterMapping;
import org.mapstruct.MappingTarget;
import org.mapstruct.factory.Mappers;

@Mapper
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);

    UserDTO toDTO(UserEntity entity);

    // 使用 @AfterMapping 注解定义映射完成后的自定义逻辑
    @AfterMapping
    default void afterMapping(@MappingTarget UserDTO dto, UserEntity entity) {
        // 将源对象的 firstName 和 lastName 拼接后赋值给目标对象的 fullName 属性
        dto.setFullName(entity.getFirstName() + " " + entity.getLastName());
    }
}

Demo示例

公共基本类定义

import lombok.Data;

// 用户实体类
@Data
public class UserEntity {
    private Long id;
    private String name;
    private Integer age;
    private String firstName;
    private String lastName;
    private AddressEntity address;
    private Long entityId;
    private String entityName;
}

// 用户数据传输对象类
@Data
public class UserDTO {
    private Long id;
    private String name;
    private Integer age;
    private String fullName;
    private AddressDTO address;
    private Long entityId;
    private String entityName;
}

// 地址实体类
@Data
public class AddressEntity {
    private String street;
    private String city;
}

// 地址数据传输对象类
@Data
public class AddressDTO {
    private String street;
    private String city;
}

简单映射示例

import org.mapstruct.Mapper;
import org.mapstruct.factory.Mappers;

@Mapper
public interface UserMapper {
    // 获取映射接口的实例
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);

    // 从 UserEntity 到 UserDTO 的映射方法
    UserDTO toDTO(UserEntity entity);
    // 从 UserDTO 到 UserEntity 的映射方法
    UserEntity toEntity(UserDTO dto);
}

// 测试代码
public class MainSimpleMapping {
    public static void main(String[] args) {
        UserEntity userEntity = new UserEntity();
        userEntity.setId(1L);
        userEntity.setName("John");
        userEntity.setAge(25);

        // 使用映射接口的实例进行映射
        UserDTO userDTO = UserMapper.INSTANCE.toDTO(userEntity);
        System.out.println("简单映射示例结果：");
        System.out.println("UserDTO: id=" + userDTO.getId() + ", name=" + userDTO.getName() + ", age=" + userDTO.getAge());
    }
}

输出结果：

简单映射示例结果：
UserDTO: id=1, name=John, age=25

字段名不一致的映射示例

import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.factory.Mappers;

@Mapper
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);

    @Mapping(source = "entityId", target = "id")
    @Mapping(source = "entityName", target = "name")
    UserDTO toDTO(UserEntity entity);

    @Mapping(source = "id", target = "entityId")
    @Mapping(source = "name", target = "entityName")
    UserEntity toEntity(UserDTO dto);
}

// 测试代码
public class MainFieldNameMismatch {
    public static void main(String[] args) {
        UserEntity userEntity = new UserEntity();
        userEntity.setEntityId(1L);
        userEntity.setEntityName("John");
        userEntity.setAge(25);

        UserDTO userDTO = UserMapper.INSTANCE.toDTO(userEntity);
        System.out.println("字段名不一致映射示例结果：");
        System.out.println("UserDTO: id=" + userDTO.getId() + ", name=" + userDTO.getName() + ", age=" + userDTO.getAge());
    }
}

输出结果：

字段名不一致映射示例结果：
UserDTO: id=1, name=John, age=25

嵌套对象映射示例

import org.mapstruct.Mapper;
import org.mapstruct.factory.Mappers;

@Mapper
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);

    UserDTO toDTO(UserEntity entity);
    UserEntity toEntity(UserDTO dto);

    AddressDTO toDTO(AddressEntity entity);
    AddressEntity toEntity(AddressDTO dto);
}

// 测试代码
public class MainNestedObjectMapping {
    public static void main(String[] args) {
        AddressEntity addressEntity = new AddressEntity();
        addressEntity.setStreet("123 Main St");
        addressEntity.setCity("New York");

        UserEntity userEntity = new UserEntity();
        userEntity.setId(1L);
        userEntity.setName("John");
        userEntity.setAddress(addressEntity);

        UserDTO userDTO = UserMapper.INSTANCE.toDTO(userEntity);
        System.out.println("嵌套对象映射示例结果：");
        System.out.println("UserDTO: id=" + userDTO.getId() + ", name=" + userDTO.getName());
        System.out.println("AddressDTO: street=" + userDTO.getAddress().getStreet() + ", city=" + userDTO.getAddress().getCity());
    }
}

输出结果：

嵌套对象映射示例结果：
UserDTO: id=1, name=John
AddressDTO: street=123 Main St, city=New York

自定义映射逻辑示例

import org.mapstruct.Mapper;
import org.mapstruct.AfterMapping;
import org.mapstruct.MappingTarget;
import org.mapstruct.factory.Mappers;

@Mapper
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);

    UserDTO toDTO(UserEntity entity);

    @AfterMapping
    default void afterMapping(@MappingTarget UserDTO dto, UserEntity entity) {
        dto.setFullName(entity.getFirstName() + " " + entity.getLastName());
    }
}

// 测试代码
public class MainCustomMappingLogic {
    public static void main(String[] args) {
        UserEntity userEntity = new UserEntity();
        userEntity.setId(1L);
        userEntity.setFirstName("John");
        userEntity.setLastName("Doe");

        UserDTO userDTO = UserMapper.INSTANCE.toDTO(userEntity);
        System.out.println("自定义映射逻辑示例结果：");
        System.out.println("UserDTO: id=" + userDTO.getId() + ", fullName=" + userDTO.getFullName());
    }
}

输出结果：

自定义映射逻辑示例结果：
UserDTO: id=1, fullName=John Doe

使用上下文示例

import org.mapstruct.Mapper;
import org.mapstruct.Context;
import org.mapstruct.factory.Mappers;
import java.util.Locale;

@Mapper
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);

    UserDTO toDTO(UserEntity entity, @Context Locale locale);

    default String localize(String value, @Context Locale locale) {
        // 根据 locale 进行本地化处理
        return value;
    }
}

// 测试代码
public class MainWithContext {
    public static void main(String[] args) {
        UserEntity userEntity = new UserEntity();
        userEntity.setId(1L);
        userEntity.setName("John");

        Locale locale = Locale.US;
        UserDTO userDTO = UserMapper.INSTANCE.toDTO(userEntity, locale);
        System.out.println("使用上下文示例结果：");
        System.out.println("UserDTO: id=" + userDTO.getId() + ", name=" + userDTO.getName());
    }
}

输出结果：

使用上下文示例结果：
UserDTO: id=1, name=John

通过以上示例可以看到，使用 MapStruct 能够方便快捷地完成 Java Bean 之间的映射，同时结合 Lombok 的 @Data 注解进一步简化了代码。并且从输出结果可以直观地验证各个映射场景的正确性。

到此这篇关于Java中基于注解的代码生成工具MapStruct映射使用详解的文章就介绍到这了,更多相关Java MapStruct内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:

相关文章

  • 流式图表拒绝增删改查之框架搭建过程

    流式图表拒绝增删改查之框架搭建过程

    这篇文章主要为大家介绍了流式图表拒绝增删改查之框架搭建过程详解，有需要的朋友可以借鉴参考下，希望能够有所帮助，祝大家多多进步，早日升职加薪
    2023-04-04
  • Springboot实现对配置文件中的明文密码加密详解

    Springboot实现对配置文件中的明文密码加密详解

    我们在SpringBoot项目当中，会把数据库的用户名密码等配置直接放在yaml或者properties文件中，这样维护数据库的密码等敏感信息显然是有一定风险的。所以本文为大家整理了对配置文件中的明文密码加密的方法，希望对大家有所帮助
    2023-03-03
  • Nacos通过RefreshScope实现配置自动更新的方式分享

    Nacos通过RefreshScope实现配置自动更新的方式分享

    这篇文章主要给大家介绍了Nacos如何通过RefreshScope实现配置自动更新,文中给了两种实现方式供大家参考,对大家的学习或工作有一定的帮助,需要的朋友可以参考下
    2023-09-09
  • 如何把Java程序窗口在屏幕中间显示

    如何把Java程序窗口在屏幕中间显示

    大家在日常Java开发中，可能会需要把程序窗口定位在屏幕中间，那该如何操作呢，下面来一起看看。
    2016-08-08
  • Java设计模式中的装饰者模式

    Java设计模式中的装饰者模式

    这篇文章主要介绍了Java设计模式中的装饰者模式，装饰者模式即Decorator Pattern，装饰模式是在不必改变原类文件和使用继承的情况下，动态地扩展一个对象的功能
    2022-07-07
  • IDEA编译报错: Error:(2048,1024) java: 找不到符号的解决办法

    IDEA编译报错: Error:(2048,1024) java: 找不到符号的解决办法

    这篇文章主要介绍了IDEA编译报错: Error:(2048,1024) java: 找不到符号的解决办法,提供了详细的排查步骤和代码示例,帮助开发者快速定位和解决该问题,需要的朋友可以参考下
    2025-05-05
  • Java中自定义泛型方法及其应用示例代码

    Java中自定义泛型方法及其应用示例代码

    泛型方法是Java中一个强大的特性,它允许我们在方法级别使用类型参数,提高代码的复用性和类型安全性,通过本文,读者可以学习如何定义和使用泛型方法,并了解其在处理集合、比较对象、创建实例等任务中的应用,感兴趣的朋友一起看看吧
    2025-02-02
  • Spring Boot + KingbaseES 连接池的实现步骤

    Spring Boot + KingbaseES 连接池的实现步骤

    本文介绍了SpringBoot+KingbaseES环境中如何选择和配置合适的数据库连接池,对比了DBCP、C3P0、Druid和HikariCP四大主流连接池的特点和配置方式,感兴趣的可以了解一下
    2026-04-04
  • 详解SpringBoot结合swagger2快速生成简单的接口文档

    详解SpringBoot结合swagger2快速生成简单的接口文档

    这篇文章主要介绍了详解SpringBoot结合swagger2快速生成简单的接口文档，小编觉得挺不错的，现在分享给大家，也给大家做个参考。一起跟随小编过来看看吧
    2019-05-05
  • Java生成独一无二的工单号实例

    Java生成独一无二的工单号实例

    这篇文章主要介绍了Java生成独一无二的工单号实例,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教
    2024-09-09

最新评论