MapStruct从入门到出门（二）

最新推荐文章于 2025-10-23 09:18:40 发布

原创最新推荐文章于 2025-10-23 09:18:40 发布 · 659 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#java #spring #java-ee

java 专栏收录该内容

13 篇文章

订阅专栏

本文详细介绍了MapStruct在Java应用中的使用，包括自动类型转换、映射引用对象、自定义映射方法、调用其他类的映射方法以及处理方法冲突。MapStruct能够自动生成转换代码，简化类型转换和对象映射过程，支持日期格式和数字格式的定制，以及引用对象的映射。同时，文章展示了如何处理方法冲突和自定义逻辑以满足特定需求。

数据类型转换

自动类型转换

在平常的对象映射中，总会有很多类型不完全一致的情况，例如Integer转Long，String转Integer或者两个自定义对象之间的转换等。在MapStruct中定义了一些类型的自动类型转换或者说是隐形类型转换。

例如在上节中提到的基本数据类型和其包装类型之间的转换，String和数字类型的转换，String和时间类型的转换等。在@Mapping注解中还可以自定义转换格式。

numberFormat属性

例如数字类型转String类型，使用numberFormat属性。

//Goods.java
@Data
@AllArgsConstructor
@NoArgsConstructor
public class Goods {

    private BigDecimal price;
}

//GoodsDto.java
@Data
public class GoodsDto {

    private String price;
}

//GoodsMapper.java

@Mapper
public interface GoodsMapper {

    GoodsMapper INSTANCE = Mappers.getMapper(GoodsMapper.class);

    @Mapping(source = "price",target = "price",numberFormat = "￥#.00")
    GoodsDto toGoodsDto(Goods goods);
}


    @Test
    void testNumberFormat(){
        Goods goods = new Goods(BigDecimal.valueOf(19.9));
        GoodsDto goodsDto = GoodsMapper.INSTANCE.toGoodsDto(goods);
        log.info("goodsDto:{}",goodsDto);
    }

//输出结果：goodsDto:GoodsDto(price=￥19.90)

使用numberFormat属性本质上就是使用java.text.DecimalFormat来实现转换的。

下面是MapStruct生成的toGoodsDto方法代码

public class GoodsMapperImpl implements GoodsMapper {

    @Override
    public GoodsDto toGoodsDto(Goods goods) {
        if ( goods == null ) {
            return null;
        }

        GoodsDto goodsDto = new GoodsDto();

        if ( goods.getPrice() != null ) {
            goodsDto.setPrice( createDecimalFormat( "￥#.00" ).format( goods.getPrice() ) );
        }

        return goodsDto;
    }

    private DecimalFormat createDecimalFormat( String numberFormat ) {

        DecimalFormat df = new DecimalFormat( numberFormat );
        df.setParseBigDecimal( true );
        return df;
    }
}

在@IterableMapping注解中也有numberFormat属性，效果跟上面是一样的。

    @IterableMapping(numberFormat = "￥#.00")
    List<String> toPricesStr(List<Integer> price);

dateFormat属性

时间类型字段例如Date，LocalDate，LocalDateTime等转String类型，可以使用dateFormat指定转换格式。

//Goods.java
@Data
@AllArgsConstructor
@NoArgsConstructor
public class Goods {

    private BigDecimal price;
    
    private Date createTime;
}

//GoodsDto.java
@Data
public class GoodsDto {

    private String price;
    
    private String createTime;

}

//GoodsMapper.java

@Mapper
public interface GoodsMapper {

    GoodsMapper INSTANCE = Mappers.getMapper(GoodsMapper.class);

    @Mapping(source = "price",target = "price",numberFormat = "￥#.00")
    @Mapping(source = "createTime",target = "createTime",dateFormat = "YYYY-MM-dd")
    GoodsDto toGoodsDto(Goods goods);
}


    @Test
    void testFormat(){
        Goods goods = new Goods(BigDecimal.valueOf(19.9),new Date());
        GoodsDto goodsDto = GoodsMapper.INSTANCE.toGoodsDto(goods);
        log.info("goodsDto:{}",goodsDto);
    }

//输出结果：goodsDto:GoodsDto(price=￥19.90, createTime=2022-06-06)

如果是Date类型和String互相转换就是使用SimpleDateFormat类来实现的。
如果是LocalDate和LocalDateTime互相转换就是使用DateTimeFormatter来实现的

其他类型转换

在MapStruct中还支持其他类的自动类型相互转换，常用的如下：

java.sql.Date和 java.util.Date
java.sql.Time 和java.util.Date
java.sql.Timestamp和 java.util.Date
String 和 StringBuilder
java.net.URL 和 String.
java.util.UUID and String

具体的可以参考[官方文档](MapStruct 1.5.1.Final Reference Guide)

映射引用对象

在平常的开发中，一个对象除了引用基本属性类型或者包装类型之外，还会引用其他对象，那么不同引用类型之间应该如何去转换？

例如下面的情况

// Car.java
@Data
@AllArgsConstructor
@NoArgsConstructor
public class Car {

    private Integer id;

    private String carName;

    private LocalDateTime createTime;

    private List<String> carInfos;

    private Person person;
}

// Person.java
@Data
@AllArgsConstructor
@NoArgsConstructor
public class Person {

    private Integer id;

    private Integer age;

    private String name;

    private LocalDateTime createTime;
}




// CarDto.java
@Data
public class CarDto {

    private String carName;

    private String publishTime;

    private List<String> carInfos;

    private PersonDto personDto;
}


// PersonDto.java
@Data
public class PersonDto {

    private Integer age;

    private String name;

    private String birthday;
}



// CarMapper.java
    @Mapping(source = "createTime",target = "publishTime",dateFormat = "YYYY-MM-dd hh:mm:ss")
    @Mapping(source = "person",target = "personDto")
    CarDto carToCarDto(Car car);

在上面的例子中，要将Car转换为CarDto类，两边分别引用着Person类型和PersonDto类型。我们编译一下代码，就会神奇的发现多了一个personToPersonDto的方法，这是MapStruct自动生成的。

@Component
public class CarMapperImpl implements CarMapper {

    private final DateTimeFormatter dateTimeFormatter_YYYY_MM_dd_hh_mm_ss_11499725216 = DateTimeFormatter.ofPattern( "YYYY-MM-dd hh:mm:ss" );

    @Override
    public CarDto carToCarDto(Car car) {
        if ( car == null ) {
            return null;
        }

        CarDto carDto = new CarDto();

        if ( car.getCreateTime() != null ) {
            carDto.setPublishTime( dateTimeFormatter_YYYY_MM_dd_hh_mm_ss_11499725216.format( car.getCreateTime() ) );
        }
        carDto.setPersonDto( personToPersonDto( car.getPerson() ) );
        carDto.setCarName( car.getCarName() );
        List<String> list = car.getCarInfos();
        if ( list != null ) {
            carDto.setCarInfos( new ArrayList<String>( list ) );
        }

        return carDto;
    }

    protected PersonDto personToPersonDto(Person person) {
        if ( person == null ) {
            return null;
        }

        PersonDto personDto = new PersonDto();

        personDto.setAge( person.getAge() );
        personDto.setName( person.getName() );

        return personDto;
    }
}

MapStruct在生成源对象和目标对象的映射方法时会遵循下列特点：

如果源属性和目标属性具有相同的类型，值将被简单地从源属性直接复制到目标属性。如果属性是一个集合（例如：List），那么集合的副本将被设置到目标属性中。

例如上面List<String>类型字段之间的映射，直接new了一个ArrayList出来并把源对象的属性作为构造参数传了进去。
如果源属性和目标属性的类型不同，那么就会检查是否存在另一个映射方法，方法参数是源属性的类型，返回类型是目标的属性类型。如果存在这样的方法，那么他会在映射方法中被调用。

例如在CarMapper接口中这样定义一个方法，那么在实现类中就会调用它。
```
@Mapping(source = "createTime",target = "birthday")
PersonDto toPersonDto(Person person);
```
如果不存在这样的方法，MapStruct将会检查目标类型的属性和源对象的属性是否可以自动转换。如果可以的话，那么他会在映射方法中被调用。
如果没有找到这样的方法，MapStruct将尝试生成一个自动的映射方法，在源和目标属性之间进行映射。像上面的personToPersonDto方法就是自动生成的映射方法。
如果MapStruct无法创建一个该映射方法，那么在编译时将会报出错误信息。

自定义映射方法

一般情况下MapStruct自动生成的代码就能够使用了，但在大部分情况下还是需要自定义映射方法，例如目标属性名和源属性名不匹配等情况。例如上面Person和PersonDto中的createTime和birthday字段一样。子映射方法和普通的映射方法使用是一样的，都是定义@Mapping注解。

    @Mapping(source = "createTime",target = "birthday")
    PersonDto toPersonDto(Person person);

当然你也可以在源方法上定义@Mapping方法，不过官方还是建议在子映射方法上来定义@Mapping注解

    @Mapping(source = "createTime",target = "publishTime",dateFormat = "YYYY-MM-dd hh:mm:ss")
    @Mapping(source = "person",target = "personDto")
    @Mapping(source = "person.createTime",target = "personDto.birthday")
    CarDto carToCarDto(Car car);

在一些情况下我们并不是要单纯的映射复制属性，而是需要通过一些自定义逻辑来生成一些属性值，这个时候就可以自定义方法逻辑体。例如下面我们给CarDto加上一个CarInfoDto类型的字段，我们需要通过车辆的发布时间来动态判断他是新品还是热销的车型。

//CarInfoDto.java
@Data
@AllArgsConstructor
@NoArgsConstructor
public class CarInfoDto {

    private String desc;
}


//CarDto.java
@Data
public class CarDto {

    private String carName;

    private String publishTime;

    private List<String> carInfos;

    // 新增字段
    private CarInfoDto carInfoDto; 

    private PersonDto personDto;
}

我们在原来的CarMapper上新增方法mapToCarInfoDto，MapStruct生成的实现类将会调用此方法来生成CarInfoDto的对象

@Mapper(componentModel = MappingConstants.ComponentModel.SPRING)
public interface CarMapper {

    @Mapping(source = "createTime",target = "publishTime",dateFormat = "YYYY-MM-dd hh:mm:ss")
    @Mapping(source = "person",target = "personDto")
    @Mapping(source = "person.createTime",target = "personDto.birthday")
    @Mapping(source = "car",target = "carInfoDto")
    CarDto carToCarDto(Car car);

//
    @Mapping(source = "createTime",target = "birthday")
    PersonDto toPersonDto(Person person);

    // 新增方法
    default CarInfoDto mapToCarInfoDto(Car car){
        LocalDateTime createTime = car.getCreateTime();
        String desc = LocalDateTime.now().getYear()==createTime.getYear()?"新品":"热销";
        return new CarInfoDto(desc);
    }

}

调用其他类的映射方法

在上面的dateFormat的例子中，我们使用该属性定义时间类型和字符串类型之间的转换格式。如果在每个类中都定义一遍那就有点繁琐了，在MapStruct中还支持调用其他类的映射方法。如下我们定义了一个DateMapper类，定义了LocalDateTime和String类之间的转换方法，需要注意一点，如果调用该类的Mapper被CI所管理的话，那么该类也需要被CI管理，例如加个@Component注解。

// DateMapper.java 
@Component
public class DateMapper {

    private final DateTimeFormatter dateTimeFormatter = DateTimeFormatter.ofPattern( "yyyy年MM月dd日 hh:mm:ss" );

    public String toString(LocalDateTime localDateTime){
        String dateTimeStr = dateTimeFormatter.format(localDateTime);
        return dateTimeStr;
    }
    
    public LocalDateTime toLocalDateTime(String dateTimeStr){
        LocalDateTime localDateTime = LocalDateTime.parse(dateTimeStr, dateTimeFormatter);
        return localDateTime;
    }
}

定义完转换类之后，修改CarMapper方法，在@Mapper注解添加uses属性，效果跟在@Mapping中定义dateFormat效果是一样的。

@Mapper(componentModel = MappingConstants.ComponentModel.SPRING,uses = DateMapper.class)
public interface CarMapper {

    @Mapping(source = "createTime",target = "publishTime")
    @Mapping(source = "person",target = "personDto")
    @Mapping(source = "person.createTime",target = "personDto.birthday")
    @Mapping(source = "car",target = "carInfoDto")
    CarDto carToCarDto(Car car);

//
    @Mapping(source = "createTime",target = "birthday")
    PersonDto toPersonDto(Person person);


    default CarInfoDto mapToCarInfoDto(Car car){
        LocalDateTime createTime = car.getCreateTime();
        String desc = LocalDateTime.now().getYear()==createTime.getYear()?"新品":"热销";
        return new CarInfoDto(desc);
    }

}

方法冲突

在有些时候会出现多个映射方法签名相同的情况，例如下面的例子,双方的入参和返回参数都相同的时候。根据MapStruct定义的映射规则，这时候会编译出错，因为不知道具体选择那个方法来作为映射。这个时候MapStruct提供了@Named注解来标识方法在通过@Mapping注解的qualifiedByName 属性来解决。

    default CarInfoDto mapToCarInfoDtoByYear(Car car){
        LocalDateTime createTime = car.getCreateTime();
        String desc = LocalDateTime.now().getYear()==createTime.getYear()?"新品":"热销";
        return new CarInfoDto(desc);
    }


    default CarInfoDto toCarInfoDtoByMonth(Car car){
        LocalDateTime createTime = car.getCreateTime();
        String desc = LocalDateTime.now().getMonthValue()==createTime.getMonthValue()?"新品":"热销";
        return new CarInfoDto(desc);
    }

具体使用代码如下

@Mapper(componentModel = MappingConstants.ComponentModel.SPRING,uses = DateMapper.class)
public interface CarMapper {

    @Mapping(source = "createTime",target = "publishTime")
    @Mapping(source = "person",target = "personDto")
    @Mapping(source = "person.createTime",target = "personDto.birthday")
    @Mapping(source = "car",target = "carInfoDto",qualifiedByName = "toCarInfoDtoByMonth")
    CarDto carToCarDto(Car car);

//
    @Mapping(source = "createTime",target = "birthday")
    PersonDto toPersonDto(Person person);


    @Named("mapToCarInfoDtoByYear")
    default CarInfoDto mapToCarInfoDtoByYear(Car car){
        LocalDateTime createTime = car.getCreateTime();
        String desc = LocalDateTime.now().getYear()==createTime.getYear()?"新品":"热销";
        return new CarInfoDto(desc);
    }

    @Named("toCarInfoDtoByMonth")
    default CarInfoDto toCarInfoDtoByMonth(Car car){
        LocalDateTime createTime = car.getCreateTime();
        String desc = LocalDateTime.now().getMonthValue()==createTime.getMonthValue()?"新品":"热销";
        return new CarInfoDto(desc);
    }

}