徹底幹掉 BeanUtils,最優雅的 Mapstruct 增強工具全新出爐

林培烈發表於2023-03-05

背景

在現在流行的系統設計中,一般會將物件模型劃分為多個層次,例如 VO、DTO、PO、BO 等等。這同時也產生了一個問題,經常需要進行不同層級的模型之間相互轉換。

針對這種問題,目前常會採用三種方案:

  1. 呼叫每個欄位的 getter/setter 進行賦值。這個過程,枯燥且乏味,容易出錯的同時,極易容易造成程式碼行數迅速膨脹,可閱讀性差。
  2. apache-commons、Spring 等提供的 BeanUtil 工具類,這種工具類使用非常方便,一行程式碼即可實現對映。但其內部採用反射的方式來實現對映,效能低下,出現問題時,除錯困難,當需要個性化轉換時,配置麻煩,非常不建議使用,特別是對於效能要求比較高的程式中。
  3. mapstruct:這個框架是基於 Java 註釋處理器,定義一個轉換介面,在編譯的時候,會根據介面類和方法相關的註解,自動生成轉換實現類。生成的轉換邏輯,是基於 getter/setter 方法的,所以不會像 BeanUtil 等消耗其效能。

上面的三種方法中,最優秀的莫屬 mapstruct 了,當然,美中不足的就是,當系統較為複雜,物件較多且結構複雜,又或者有的專案設計中會定義多層物件模型(如 DDD 領域設計),需要定義較多的轉換介面和轉換方法,這也是一些開發者放棄 Mapstruct 的主要原因。

這裡,就要給大家介紹一個 Mapstruct 的增強包 —— Mapstruct Plus,一個註解,可以生成兩個類之間的轉換介面,使 Java 型別轉換更加便捷、優雅,徹底拋棄 BeanUtils。

快速開始

下面演示如何使用 MapStruct Plus 來對映兩個物件。

假設有兩個類 UserDtoUser,分別表示資料層物件和業務層物件:

  • UserDto
public class UserDto {
    private String username;
    private int age;
    private boolean young;

    // getter、setter、toString、equals、hashCode
}
  • User
public class User {
    private String username;
    private int age;
    private boolean young;

    // getter、setter、toString、equals、hashCode
}

新增依賴

引入 mapstruct-plus-spring-boot-starter 依賴:

<properties>
    <mapstruct-plus.version>1.1.3</mapstruct-plus.version>
</properties>
<dependencies>
    <dependency>
        <groupId>io.github.linpeilie</groupId>
        <artifactId>mapstruct-plus-spring-boot-starter</artifactId>
        <version>${mapstruct-plus.version}</version>
    </dependency>
</dependencies>
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
                <annotationProcessorPaths>
                    <path>
                        <groupId>io.github.linpeilie</groupId>
                        <artifactId>mapstruct-plus-processor</artifactId>
                        <version>${mapstruct-plus.version}</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

指定物件對映關係

User 或者 UserDto 上面增加註解 —— @AutoMapper,並設定 targetType 為對方類。

例如:

@AutoMapper(target = UserDto.class)
public class User {
    // ...
}

測試

@SpringBootTest
public class QuickStartTest {

    @Autowired
    private Converter converter;

    @Test
    public void test() {
        User user = new User();
        user.setUsername("jack");
        user.setAge(23);
        user.setYoung(false);

        UserDto userDto = converter.convert(user, UserDto.class);
        System.out.println(userDto);    // UserDto{username='jack', age=23, young=false}

        assert user.getUsername().equals(userDto.getUsername());
        assert user.getAge() == userDto.getAge();
        assert user.isYoung() == userDto.isYoung();

        User newUser = converter.convert(userDto, User.class);

        System.out.println(newUser);    // User{username='jack', age=23, young=false}

        assert user.getUsername().equals(newUser.getUsername());
        assert user.getAge() == newUser.getAge();
        assert user.isYoung() == newUser.isYoung();
    }

}

小結

引入依賴後,使用 Mapstruct Plus 步驟非常簡單。

  1. 給需要轉換的類新增 AutoMapper 註解
  2. 獲取 Converter 例項,呼叫 convert 方法即可

特性

完全相容 Mapstruct

Mapst實現了增強操作,如果之前已經使用了 Mapstruct,可以直接替換相關依賴。

單註解即可實現兩個物件相互轉換

例如快速開始中,只在 User 類上面增加註解 @AutoMapper,Mapstruct Plus 除了會生成 User -> UserDto 的轉換介面,預設還會生成 UserDto -> User 的轉換介面。

編譯後,可以檢視生成的類,如下:

image.png

自定義物件型別的屬性自動轉換

當兩個需要轉換的物件 AADto,其中的屬性 BBDto 是自定義型別,並且也定義了 @AutoMapper 註解的話,在生成轉換 AADto 時,會自動依賴屬性 BBDto 的轉換介面,實現其相應的屬性轉換。

例如:
分別有兩組物件模型:汽車(Car) 和座椅配置(SeatConfiguration),其中 Car 依賴 SeatConfiguration。

兩組物件結構一致,只不過代表層級不一樣,這裡拿 dto 層的物件定義舉例:

  • CarDto
@AutoMapper(target = Car.class)
public class CarDto {
    private SeatConfigurationDto seatConfiguration;
}
  • SeatConfiguration
@AutoMapper(target = SeatConfiguration.class)
public class SeatConfigurationDto {
    private int seatCount;
}

測試:

@Test
public void carConvertTest() {
    CarDto carDto = new CarDto();
    SeatConfigurationDto seatConfigurationDto = new SeatConfigurationDto();
    seatConfigurationDto.setSeatCount(4);
    carDto.setSeatConfiguration(seatConfigurationDto);

    final Car car = converter.convert(carDto, Car.class);
    System.out.println(car);    // Car(seatConfiguration=SeatConfiguration(seatCount=4))

    assert car.getSeatConfiguration() != null;
    assert car.getSeatConfiguration().getSeatCount() == 4;
}

單個物件對多個物件進行轉換

Mapstruct Plus 提供了 @AutoMappers 註解,支援配置多個目標物件,進行轉換。

例如:有三個物件,UserUserDtoUserVOUser 分別要和其他兩個物件進行轉換。則可以按如下配置:

@Data
@AutoMappers({
    @AutoMapper(target = UserDto.class),
    @AutoMapper(target = UserVO.class)
})
public class User {
    // ...
}

Map 轉物件

Mapstruct Plus 提供了 @AutoMapMapper 註解,支援生成 Map<String, Object> 轉換為當前類的介面。同時,還支援 map 中巢狀 Map<String, Object> 轉換為自定義類巢狀自定義類的場景。

其中,map 中的 value 支援的型別如下:

  • String
  • BigDecimal
  • BigInteger
  • Integer
  • Long
  • Double
  • Number
  • Boolean
  • Date
  • LocalDateTime
  • LocalDate
  • LocalTime
  • URI
  • URL
  • Calendar
  • Currency
  • 自定義類(自定義類也需要增加 @AutoMapMapper 註解

例如:

有如下兩個介面:

  • MapModelA
@Data
@AutoMapMapper
public class MapModelA {

    private String str;
    private int i1;
    private Long l2;
    private MapModelB mapModelB;

}
  • MapModelB
@Data
@AutoMapMapper
public class MapModelB {

    private Date date;
    
}

測試:

@Test
public void test() {
    Map<String, Object> mapModel1 = new HashMap<>();
    mapModel1.put("str", "1jkf1ijkj3f");
    mapModel1.put("i1", 111);
    mapModel1.put("l2", 11231);

    Map<String, Object> mapModel2 = new HashMap<>();
    mapModel2.put("date", DateUtil.parse("2023-02-23 01:03:23"));

    mapModel1.put("mapModelB", mapModel2);

    final MapModelA mapModelA = converter.convert(mapModel1, MapModelA.class);
    System.out.println(mapModelA);  // MapModelA(str=1jkf1ijkj3f, i1=111, l2=11231, mapModelB=MapModelB(date=2023-02-23 01:03:23))
}

支援自定義轉換

自定義屬性轉換

Mapstruct Plus 提供了 @AutoMapping 註解,該註解在編譯後,會變為 Mapstruct 中的 @Mapping 註解,已經實現了幾個常用的註解屬性。

指定不同名稱屬性欄位對映轉換

例如,Car 類中屬性 wheels 屬性,轉換 CarDto 型別時,需要將該欄位對映到 wheelList 上面,可以在 wheels 上面增加如下註解:

@AutoMapper(target = CarDto.class)
public class Car {
    @AutoMapping(target = "wheelList")
    private List<String> wheels;
}

自定義時間格式化

在將 Date 型別的屬性,轉換為 String 型別時,可以透過 dateFormat 來指定時間格式化:

@AutoMapper(target = Goods.class)
public class GoodsDto {

    @AutoMapping(target = "takeDownTime", dateFormat = "yyyy-MM-dd HH:mm:ss")
    private Date takeDownTime;

}

自定義數字格式化

當數字型別(doublelongBigDecimal)轉換為 String 型別時,可以透過 numberFormat 指定 java.text.DecimalFormat 所支援的格式:

@AutoMapper(target = Goods.class)
public class GoodsDto {

    @AutoMapping(target = "price", numberFormat = "$#.00")
    private int price;

}

自定義 Java 表示式

@AutoMapping 提供了 expression 屬性,支援配置一段可執行的 Java 程式碼,來執行具體的轉換邏輯。

例如,當一個 List<String> 的屬性,想要轉換為用 , 分隔的字串時,可以透過該配置,來執行轉換邏輯:

@AutoMapper(target = UserDto.class)
public class User {

    @AutoMapping(target = "educations", expression = "java(java.lang.String.join(",", source.getEducationList()))")
    private List<String> educationList;

}

自定義型別轉換器

@AutoMapping 註解提供了 uses 屬性,引入自定義的型別轉換器,來提供給當前類轉換時使用。

例項場景:

專案中會有字串用 , 分隔,在一些類中,需要根據逗號拆分為字串集合。針對於這種場景,可以有兩種方式:首先可以指定欄位對映時的表示式,但需要對每種該情況的欄位,都新增表示式,複雜且容易出錯。

第二,就可以自定義一個型別轉換器,透過 uses 來使用

public interface StringToListString {
    default List<String> stringToListString(String str) {
        return StrUtil.split(str);
    }
}

@AutoMapper(target = User.class, uses = StringToListStringConverter.class)
public class UserDto {

    private String username;
    private int age;
    private boolean young;
    @AutoMapping(target = "educationList")
    private String educations;
    // ......
}

測試:


@SpringBootTest
public class QuickStartTest {

    @Autowired
    private Converter converter;

    @Test
    public void ueseTest() {
        UserDto userDto = new UserDto();
        userDto.setEducations("1,2,3");

        final User user = converter.convert(userDto, User.class);
        System.out.println(user.getEducationList());    // [1, 2, 3]

        assert user.getEducationList().size() == 3;
    }
}

更多

更多特性,可以檢視官方文件

結束語

Mapstruct Plus 相對於 Mapstruct 來說,繼承了其高效能的特點,同時增強了其便攜性和快速開發的特性,在系統模型設計較好(屬性及型別基本一致)的情況下,開發成本極低,是時候和 BeanUtils 說再見了。

相關文章