碍于面子，偷偷学了 MapStruct

uzong
5,885 阅读9分钟

最近入职新公司，发现大家都在用 MapStruct，以前都是用的 BeanUtil，不好意思问同事，只能偷偷学。

MapStruct 介绍

官网文章 mapstruct.org/documentati…

是什么

MapStruct 是一个代码注解生成器，用于简化 Java Bean 之间映射的实现。它通过约定优于配置的方式，在编译时生成类型安全的映射代码，无需反射，性能出色。

MapStruct的核心优势：

  1. 编译时生成代码：无反射开销，性能最优，生成纯 Java 代码
  2. 类型安全：编译期即可发现错误。（eg:源和目标类型不匹配则报错）
  3. 易调试：生成的代码清晰可读。（基于注解，简单好用）
  4. IDE友好：完善的工具支持

实现案例

老规矩，快速搭建一个应用，尝试一下 MapStruct 的功能

仓库

git 仓库地址：gitee.com/uzongn/maps…

maven 工程要点

编译时生成代码，需要 maven 等插件支持。在项目的pom.xml文件中添加MapStruct的依赖和处理器（processor）配置

<configuration>
  <annotationProcessorPaths>
    <path>
      <groupId>org.mapstruct</groupId>
      <artifactId>mapstruct-processor</artifactId>
      <version>1.5.5.Final</version>
    </path>
  </annotationProcessorPaths>
</configuration>

完整依赖，可以查看代码或者官网。

接下来正式进入学习环境

入门教程

核心注解

@Mapper 映射接口

定义一个映射器接口，并使用@Mapper注解标记。在接口中声明源对象和目标对象之间的映射方法。

// Mapper接口
@Mapper
public interface UserMapper {
    UserDTO userToUserDTO(User user);
    User userDTOToUser(UserDTO userDTO);
}

只需要定义这样一个接口就可以了。

使用 @Mapper 注解会通过 MapStruct 代码生成器在代码编译构建时生成一个具体实现。

MapStruct会在编译时自动生成映射代码，因此可以直接使用映射接口进行对象之间的映射

User user = new User("John", "Doe");
UserDTO userDTO = userMapper.userToUserDTO(user);

MapStruct也支持集合的映射

@Mapper
public interface UserMapper {
    List<UserDTO> usersToUserDTOs(List<User> users);
}

@Mapping 映射

当源实体中的字段与目标中的字段一致时，默认直接映射，如果不一致，可以通过 @Mapping 做映射。

可以使用@Mapping注解来指定源属性和目标属性之间的映射关系。

比如将 Car#numberOfSeats 映射到 CarDto#seatCount

@Mapper
public interface CarMapper {
    @Mapping(source = "numberOfSeats", target = "seatCount")
    @Mapping(source = "type", target = "carType")
    CarDto carToCarDto(Car car);
}

多数据源的映射

public interface AddressMapper {
    @Mapping(source = "person.firstName", target = "firstName")
    @Mapping(source = "address.street", target = "street")
    AddressDto personAndAddressToAddressDto(Person person, Address address);
}

将 Person#firstName 映射到 AddressDto#firstName ； 将 Address#street 映射到 AddressDto#street

注意在 Java8 之前的版本，不支持重复注解。需要使用 @Mappings

  // before Java 8
  @Mapper
  public interface MyMapper {
      @Mappings({
          @Mapping(target = "firstProperty", source = "first"),
          @Mapping(target = "secondProperty", source = "second")
      })
      HumanDto toHumanDto(Human human);
  }

还可以指定默认值（defaultValue） 和 常量（constant）

@Mapping(target = "tag", source = "tag", defaultValue = "默认值") 
@Mapping(target = "longWrapperConstant", constant = "3001")
PersonDTO conver(Person person);

@MappingTarget

使用@MappingTarget描述。但是在方法中使用，只能设置一个，注意方法参数都不能为 null

举例如下

  @Mapper
  public interface HumanMapper {
      void updateHuman(HumanDto humanDto, @MappingTarget Human human);
  }

实际代码生成情况

  // generates
  @Override
  public void updateHuman(HumanDto humanDto, Human human) {
      human.setName( humanDto.getName() );
      // ...
  }

所以参数不能为 null。否则 NPE

@ValueMapping （ValueMappings）

枚举映射的情况。（映射不同的值）

// 源枚举
public enum PaymentStatus {
    PENDING,
    PROCESSING,
    COMPLETED,
    FAILED,
    CANCELLED
}

// 目标枚举
public enum PaymentStatusEntity {
    INIT,
    IN_PROGRESS,
    SUCCESS,
    ERROR,
    TERMINATED
}

@Mapper(componentModel = "spring")
public interface PaymentMapper {
    @ValueMappings({
        @ValueMapping(source = "PENDING", target = "INIT"),
        @ValueMapping(source = "PROCESSING", target = "IN_PROGRESS"),
        @ValueMapping(source = "COMPLETED", target = "SUCCESS"),
        @ValueMapping(source = "FAILED", target = "ERROR"),
        @ValueMapping(source = "CANCELLED", target = "TERMINATED"),
        @ValueMapping(source = MappingConstants.NULL, target = "INIT"),
        @ValueMapping(source = MappingConstants.ANY_REMAINING, target = "ERROR")
    })
    PaymentStatusEntity mapStatus(PaymentStatus status);
}

字符串到枚举


@Mapper(componentModel = "spring")
public interface StatusMapper {
    @ValueMappings({
        @ValueMapping(source = "A", target = "ACTIVE"),
        @ValueMapping(source = "I", target = "INACTIVE"),
        @ValueMapping(source = "P", target = "PENDING"),
        @ValueMapping(source = MappingConstants.NULL, target = "UNKNOWN"),
        @ValueMapping(source = MappingConstants.ANY_REMAINING, target = "UNKNOWN")
    })
    UserStatus mapStatus(String statusCode);

    default UserStatus safeMapStatus(String statusCode) {
        try {
            return mapStatus(statusCode);
        } catch (IllegalArgumentException e) {
            return UserStatus.UNKNOWN;
        }
    }
}

@BeforeMapping/@AfterMapping

@BeforeMapping 和 @AfterMapping 允许在映射过程的前后执行自定义逻辑。

@Mapper(componentModel = "spring")
public abstract class UserMapper {
    @BeforeMapping
    protected void validateUserDto(UserDto source) {
        if (source == null) {
            throw new IllegalArgumentException("UserDto cannot be null");
        }
        if (StringUtils.isEmpty(source.getEmail())) {
            throw new IllegalArgumentException("Email is required");
        }
    }
    
    @AfterMapping
    protected void enrichUserEntity(@MappingTarget UserEntity target) {
        target.setLastUpdateTime(LocalDateTime.now());
        target.setVersion(target.getVersion() + 1);
    }
    
    @Mapping(target = "id", source = "userId")
    @Mapping(target = "email", source = "emailAddress")
    public abstract UserEntity toEntity(UserDto source);
}

@BeanMapping

属于 bean 级别的配置，不仅仅单个字段。该注解提供了多种配置选项来控制 bean 之间的映射行为

  1. nullValueMappingStrategy：当 null 作为源值传递给映射的方法时要应用的策略。默认值为 NullValueMappingStrategy.RETURN_NULL。
@BeanMapping(nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT)
PersonDto personToPersonDto(Person person);

2. ignoreByDefault：默认忽略所有映射，所有映射都必须手动定义，不会发生自动映射。默认值为 false。

@BeanMapping(ignoreByDefault = true)
@Mapping(target = "name", source = "fullName")
PersonDto personToPersonDto(Person person);

通常在有多个可能的映射目标类型时使用，或者当你想要明确指定返回类型的映射器方法时使用

假设我们有两个 DTO 类型，CarDto 和 CarDetailDto，它们都包含 Car 实体的一些属性，但是 CarDetailDto 包含了一些额外的详细信息

public class Car {
    private String brand;
    private String model;
    // 省略其他属性和getter/setter方法
}

public class CarDto {
    private String brand;
    private String model;
    // 省略其他属性和getter/setter方法
}

public class CarDetailDto extends CarDto {
    private String color;
    private int year;
    // 省略其他属性和getter/setter方法
}

创建一个映射器，它可以根据条件返回 CarDto 或 CarDetailDto。可以使用 resultType 确定

@Mapper
public interface CarMapper {

    @BeanMapping(resultType = CarDto.class)
    CarDto mapToCarDto(Car car);

    @BeanMapping(resultType = CarDetailDto.class)
    CarDetailDto mapToCarDetailDto(Car car);
}

在这个例子中，mapToCarDto 方法将 Car 实体映射到 CarDto，而 mapToCarDetailDto 方法将 Car 实体映射到 CarDetailDto。通过使用 resultType，我们明确指定了每个映射方法的结果类型，这样 MapStruct 就可以根据调用的方法生成正确的映射代码。

  1. 忽略哪些字段,ignoreUnmappedSourceProperties

例如下面：internalId、systemFields 忽略这两个字段。

@Mapper
public interface OrderMapper {
    @BeanMapping(
        ignoreUnmappedSourceProperties = {"internalId", "systemFields"},  // 忽略源对象中的特定字段
        unmappedTargetPolicy = ReportingPolicy.ERROR,                    // 未映射目标字段时报错
        nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.SET_TO_DEFAULT  // null值使用默认值
    )
    @Mapping(target = "orderNumber", source = "id")
    OrderDto toDto(Order order);
}

场景解决方案

类型不匹配

源实体和目标实体中映射属性的类型不同，

MapStruct 会自动转换。如果不能，则需要自定义映射器

多数据源情况

如果多个 source 对象定义了一个同名的属性，则必须使用 @Mapping 注释指定要从中检索属性的 source 参数，如果未解决此类歧义，则会引发错误

自定义类型转换

针对日期做特定解析和转换

@Mapper(componentModel = "spring")
public abstract class UserMapper {
    // 自定义转换方法
    @Named("stringToLocalDate")
    protected LocalDate stringToLocalDate(String date) {
        if (date == null) {
            return null;
        }
        return LocalDate.parse(date, DateTimeFormatter.ISO_DATE);
    }
    
    @Mapping(source = "birthDate", target = "dateOfBirth", qualifiedByName = "stringToLocalDate")
    public abstract UserEntity toEntity(UserDto dto);
}

qualifiedByName && @Named("stringToLocalDate")

qualifiedByName: 这个参数允许你引用一个具有@Named注解的方法作为自定义的映射逻辑。

本案例：toEntity 方法，将 UserDto 中的 birthDate 字段，类型为 String，通过stringToLocalDate转成 LocalDate，设置到目标 UserEntity 中的 dateOfBirth 字段里面

表达式映射 expression

@Mapper(componentModel = "spring")
public interface OrderMapper {
    @Mapping(target = "fullName",
            expression = "java(source.getFirstName() + " " + source.getLastName())")
    @Mapping(target = "totalPrice",
            expression = "java(calculateTotal(source.getPrice(), source.getTax()))")
    OrderEntity toEntity(OrderDto source);
    
    default BigDecimal calculateTotal(BigDecimal price, BigDecimal tax) {
        if (price == null) return BigDecimal.ZERO;
        if (tax == null) return price;
        return price.add(price.multiply(tax));
    }
}

当前 Java 是唯一受支持的“表达式语言”，表达式必须以 Java 表达式的形式给出，格式如下：java（<EXPRESSION>）。

注意：

  • 不能 与 source(), defaultValue(), defaultExpression(), qualifiedBy(), qualifiedByName() or constant() 一起使用。

  • 要使用全限定类名

  • 默认表达式是默认值和表达式的组合。仅当 source 属性为 null 时，才会使用它们.

Null 的应对策略（Mapping注解中的选项）

public enum NullValuePropertyMappingStrategy {
    SET_TO_NULL,
    SET_TO_DEFAULT,
    IGNORE;

    private NullValuePropertyMappingStrategy() {
    }
}

SET_TO_NULL: 如果 source 的 bean 的字段为 null，目标也设置为 null

SET_TO_DEFAULT： 如果 source 的 bean 的字段为 null，目前根据实际类型设置默认值。

  1. List 设置成 ArrayList
  2. Map 设置成 HashMap
  3. array 设置成空数组 []
  4. 字符串 “”
  5. 基础类型或者包装类型，设置 0 或者 false
  6. 其他对象类型，创建一个无参对象。

IGNORE：忽略，目标 bean 保留现有值，不做任何处理。


@Mapper(componentModel = "spring")
public interface AddressMapper {
    
    AddressDTO toDTO(Address address);
    
    Address toEntity(AddressDTO dto);
    
    @BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
    void updateAddressFromDTO(AddressDTO dto, @MappingTarget Address address);
}

其他特性

支持抽象

映射器也可以以抽象类而不是接口的形式定义，并直接在映射器类中实现自定义方法。在这种情况下，MapStruct 将生成抽象类的扩展，其中包含所有抽象方法的实现。与声明默认方法相比，这种方法的一个优点是可以在 mapper 类中声明其他字段

@Mapper
public abstract class CarMapper {

    @Mapping(...)
    ...
    public abstract CarDto carToCarDto(Car car);

    public PersonDto personToPersonDto(Person person) {
        //hand-written mapping logic
    }
}

Map 映射

在某些情况下Map<String, ???>到特定的 bean 中。MapStruct 通过使用目标 bean 属性（或通过 Mapping#source 定义）从 Map 中提取值，提供了一种执行此类映射的透明方式。

public class Customer {

    private Long id;
    private String name;

    //getters and setter omitted for brevity
}

@Mapper
public interface CustomerMapper {

    @Mapping(target = "name", source = "customerName")
    Customer toCustomer(Map<String, String> map);

}

Mappers

映射器工厂，方便管理所有的 Mapper

public static <T> T getMapper(Class<T> clazz) {
    try {
        List<ClassLoader> classLoaders = collectClassLoaders( clazz.getClassLoader() );

        return getMapper( clazz, classLoaders );
    }
    catch ( ClassNotFoundException | NoSuchMethodException e ) {
        throw new RuntimeException( e );
    }
}

声明和使用方式

当不使用DI容器(比如 spring 容器)， 可以通过 org.mapstruct.factory.Mappers 类检索 Mapper 实例。只需调用 getMapper() 方法，

如果需要依赖注入，需要指定 ComponentModel， 如下所示：

ComponentModel

@Mapper(componentModel = "spring")
public interface AddressMapper {
    
    AddressDTO toDTO(Address address);
    
    Address toEntity(AddressDTO dto);
    
    @BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
    void updateAddressFromDTO(AddressDTO dto, @MappingTarget Address address);
}

依赖注入，交给 spring 进行管理。

将生成一个 SpringBean，可以通过@Autowired 被使用。

最终生成的代码。使用@Component 进行修饰。

@Mapper(componentModel = "spring", uses = {UserMapper.class})
public interface UserMapper {
    ......
}

uses 当前映射器可以使用其他映射器

前映射器在执行映射时可以调用这些映射器的方法，UserMapper 中，可以使用UserMapper，

原理

编译时生成具体实现类，相关方法的实现，就是按照 set、get 对相同字段做映射。

不是通过反射生成，这一点性能肯定是要快很多的。

IDEA 插件-MapStruct-Support

  • target、source、expression 中的代码补全
  • 重构支持
  • ......

插件地址：plugins.jetbrains.com/plugin/1003…

常见问题和解决方案

问题一、被不同版本编译

Caused by: java.lang.UnsupportedClassVersionError: com/example/mapper/AddressMapperImpl has been compiled by a more recent version of the Java Runtime (class file version 55.0), this version of the Java Runtime only recognizes class file versions up to 52.0

手动删除 target 后重新启动应用即可。或者 mvn clean

问题二、lombok 兼容

Lombok 1.18.16 引入了重大更改（更改日志）。必须添加附加注释处理器 lombok-mapstruct-binding (Maven)，否则 MapStruct 将停止与 Lombok 配合使用。

解决了 Lombok 和 MapStruct 模块的编译问题

<path>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok-mapstruct-binding</artifactId>
    <version>0.2.0</version>
</path>

问题三、缓存问题

使用 MapStruct 在 IDEA 社区版中老是出现类找不到、编译问题。（比较坑）

最后

对于 MapStruct 的基本使用，目前基本不成问题，上面内容已经能够覆盖90%的场景了。对于一些高级玩法，有兴趣自行研究。

本文到此结束，感谢阅读，下期再见！

avatar
文章
阅读
粉丝