MapStruct Plus的使用教程
前言
Mapstruct 是一個代碼生成器，基于約定優(yōu)于配置的方法，極大簡化了 Java bean 類型之間映射的實現(xiàn)，特點：速度快、類型安全且易于理解。
Mapstruct Plus 是 MapStruct 的增強工具（類似于 Mybatis 和 Mybatis Plus 的關(guān)系），其在 MapStruct 的基礎(chǔ)上，實現(xiàn)了自動生成 Mapper 接口的功能，并強化了部分功能，使 Java 類型轉(zhuǎn)換更便捷、優(yōu)雅。
MapStruct Plus 內(nèi)嵌 MapStruct，和 MapStruct 完全兼容，如果之前已經(jīng)使用 MapStruct，可以無縫替換依賴。
參考網(wǎng)站：
MapStruct 官網(wǎng)
MapStruct Plus 官網(wǎng)
一、為什么要用 MapStruct（背景）
目前的系統(tǒng)開發(fā)中，對象模型之間需要相互轉(zhuǎn)換，比如一個 User 對象需要轉(zhuǎn)換為 UserVo 對象：
@Data
public class User {
private String name;
private int age;
private String password;
}
@Data
public class UserVo {
private String name;
private int age;
}
常規(guī)的有兩種方式：
- 使用 getter 和 setter 方法進(jìn)行賦值，但是這個方法有著大量枯燥且重復(fù)的工作，一旦出錯也不易于發(fā)現(xiàn)，可讀性差。
- 使用 spring 提供的
BeanUtils工具類進(jìn)行對象之間的轉(zhuǎn)換，如下代碼塊所示，但是因為內(nèi)部采用反射實現(xiàn)，性能低下，出現(xiàn)問題時不容易調(diào)試。
// 創(chuàng)建一個 User 對象
User user = new User();
user.setName("wen");
user.setAge(18);
user.setPassword("123456");
// 創(chuàng)建一個 UserVo 對象
UserVo userVo = new UserVo();
// 一行代碼實現(xiàn) user => userVo
BeanUtils.copyProperties(user, userVo);
所以 MapStruct 應(yīng)運而生，這個框架是基于 Java 注釋處理器，定義一個轉(zhuǎn)換接口，在編譯的時候會根據(jù)接口類和方法相關(guān)的注解，自動生成實現(xiàn)類，底層是基于 getter 和 setter 方法的，比 BeanUtils 的性能要高。然而美中不足的是，當(dāng)需要轉(zhuǎn)換的對象較多或者結(jié)構(gòu)復(fù)雜的時候，需要定義較多的轉(zhuǎn)換接口和轉(zhuǎn)換方法。
此時，就可以使用 MapStruct Plus ，一個注解就可以生成兩個類之間的轉(zhuǎn)換接口，使 Java 類型轉(zhuǎn)換更加便捷和優(yōu)雅。
二、MapStruct Plus 的快速開始
本文以 Spring Boot 項目為例，版本：
Spring Boot：3.3.2
JDK：17
Lombok：1.18.34
1. 引入依賴
引入 mapstruct-plus-spring-boot-starter 依賴
<dependency>
<groupId>io.github.linpeilie</groupId>
<artifactId>mapstruct-plus-spring-boot-starter</artifactId>
<version>1.4.3</version>
</dependency>
引入 Maven 插件，配置項目的構(gòu)建過程（這一步非常非常重要?。。。?/strong>引入 Maven 插件，配置項目的構(gòu)建過程（這一步非常非常重要?。。。?/strong>引入 Maven 插件，配置項目的構(gòu)建過程（這一步非常非常重要！?。。?/strong>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<configuration>
<source>17</source>
<target>17</target>
<annotationProcessorPaths>
<path>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>${lombok.version}</version>
</path>
<path>
<groupId>io.github.linpeilie</groupId>
<artifactId>mapstruct-plus-processor</artifactId>
<version>${mapstruct-plus.version}</version>
</path>
<path>
<groupId>org.projectlombok</groupId>
<artifactId>lombok-mapstruct-binding</artifactId>
<version>0.2.0</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
</plugins>
</build>
最新版本依賴可以查看：MapStruct Plus 的 Maven 倉庫地址
2. 指定對象映射關(guān)系
在 User 或者 UserVo 上面增加注解 —— @AutoMapper，并設(shè)置 target 為對方類。
以下面代碼舉例，添加注解：@AutoMapper(target = UserVo.class)
- User 類
@Data
@AutoMapper(target = UserVo.class)
public class User {
private String username;
private int age;
private String password;
}
- UserVo 類
@Data
@AutoMapper(target = UserVo.class)
public class User {
private String username;
private int age;
private String password;
}
3. 編寫測試代碼
@SpringBootTest
public class QuickStartTest {
@Autowired
private Converter converter;
@Test
public void test() {
// 創(chuàng)建 User 對象
User user = new User();
user.setUsername("wen");
user.setAge(18);
user.setPassword("123456");
// 使用 MapStruct plus 進(jìn)行對象間轉(zhuǎn)換：User =》 UserVo
UserVo userVo = converter.convert(user, UserVo.class);
// 輸出轉(zhuǎn)換之后的對象
System.out.println(userVo);
// 斷言測試
assert user.getUsername().equals(userVo.getUsername());
assert user.getAge() == userVo.getAge();
}
}
4. 運行結(jié)果
測試通過，輸出：
5. 原理解析
通過以上示例可以看出，User 對象轉(zhuǎn)化為 UserVo 對象主要是UserVo userVo = converter.convert(user, UserVo.class);這行代碼，其底層也很簡單，原理是通過 getter 和 setter 實現(xiàn)的：
public UserVo convert(User arg0) {
if ( arg0 == null ) {
return null;
}
UserVo userVo = new UserVo();
userVo.setUsername( arg0.getUsername() );
userVo.setAge( arg0.getAge() );
return userVo;
}
該代碼被保存在 target 包中，具體路徑：target/generated-sources/annotations/實體類存放路徑
通過上圖，可以看到，哪怕沒有給 UserVo 實體類使用@AutoMapper注解，MapStruct Plus 會自動生成 User 轉(zhuǎn) UserVo 的接口和實現(xiàn)類，同時也會生成 UserVo 轉(zhuǎn)換為 User 的實體類和接口。
以上為重要規(guī)則，下面也能用得到！??！
三、自定義實體類中的屬性轉(zhuǎn)換
在上面的例子中，兩個實體類中對應(yīng)的屬性都是同一種類型，那么想要自定義屬性比如：后端存儲的是字符串 String 類型的屬性，想給前端返回一個 List 類型的屬性，可以根據(jù)規(guī)則進(jìn)行轉(zhuǎn)換。
下面的舉例是 String 屬性和 List 屬性之間的相互轉(zhuǎn)化（String 《===》List）
有兩種方式：
- 自定義一個類型轉(zhuǎn)換器，通過
@AutoMapper的uses屬性引入 - 通過
@AutoMapping中配置的expression表達(dá)式配置
1. 自定義一個類型轉(zhuǎn)換器
首先定義兩個類型轉(zhuǎn)換器，一個是 String 轉(zhuǎn)為 List，一個是 List 是 String。且兩個類型轉(zhuǎn)換器需要定義為 Spring 的 Bean，即使用 @Component 注解。
String 轉(zhuǎn)為 List 的轉(zhuǎn)換器：
@Component
public class StringToListConverter {
public List<String> stringToList(String str) {
if (str == null) {
return Collections.emptyList();
}
return Arrays.asList(str.split(","));
}
}
List 轉(zhuǎn)為 String 的轉(zhuǎn)換器：
@Component
public class ListToStringConverter {
public String listToString(List<String> list) {
if (list == null || list.isEmpty()) {
return null;
}
return String.join(",", list);
}
}
2. 使用類型轉(zhuǎn)換器
第二步，使用該類型轉(zhuǎn)換器，即在 @AutoMapper 注解中使用 uses，且給需要轉(zhuǎn)化的屬性加上 @AutoMapping 注解，target 指向另一個需要轉(zhuǎn)化的屬性。
User 類：
@Data
@AutoMapper(target = UserVo.class, uses = StringToListConverter.class)
public class User {
private String name;
private int age;
private String password;
@AutoMapping(target = "tagList")
private String tags;
}
UserVo 類：
@Data
@AutoMapper(target = User.class, uses = ListToStringConverter.class)
public class UserVo {
private String name;
private int age;
@AutoMapping(target = "tags")
private List<String> tagList;
}
3. 進(jìn)行測試
第三步，進(jìn)行測試。
@SpringBootTest
public class QuickStartTest {
@Autowired
private Converter converter;
@Test
public void test() {
// 創(chuàng)建一個 User 對象
User user = new User();
user.setName("wen");
user.setAge(18);
user.setPassword("123456");
user.setTags("Java,Python,C++");
// 轉(zhuǎn)換
UserVo userVo = converter.convert(user, UserVo.class);
System.out.println(userVo);
assert userVo.getTagList().size() == 3;
}
}
測試結(jié)果：
測試用例通過，User 類中的 String 類型的 tags 屬性，成功轉(zhuǎn)化為 UserVo 類中的 List 類型的 tagList 屬性。
還有一種方法是直接在注解中寫表達(dá)式，但是博主覺得這種方式?jīng)]有自定義轉(zhuǎn)換器好，所以在本文中不列舉
如果感興趣，詳情請參考：表達(dá)式自定義屬性轉(zhuǎn)換
四、Map 轉(zhuǎn)為 Object
MapStruct Plus 提供了 Map<String, Object> 轉(zhuǎn)化為對象的功能。
轉(zhuǎn)換邏輯：針對目標(biāo)類中的一個屬性，首先會判斷 Map 中是否存在該鍵，如果存在的話，首先判斷類型，
- 如果類型相同，直接強轉(zhuǎn)
- 若果類型不同，會使用 Hutool 提供的類型轉(zhuǎn)換工具嘗試轉(zhuǎn)換為目標(biāo)類型
MapStruct Plus 在 1.4.0+ 版本取消了內(nèi)置 Hutool 框架，如果需要用到 Map 轉(zhuǎn)化為對象的功能時，需要引入 hutool-core 這個依賴，最新版本查看：Hutool 依賴庫
<dependency> <groupId>cn.hutool</groupId> <artifactId>hutool-core</artifactId> <version>5.8.29</version> </dependency>
1. 使用步驟
- 引入
hutool-core依賴 - 在目標(biāo)類上添加
@AutoMapMapper注解 - 同時支持自定義類作為屬性，需要在自定義類上增加
@AutoMapMapper注解
2. 定義對象
為了更好的理解，直接用最復(fù)雜的 Map 轉(zhuǎn)對象的例子舉例，即內(nèi)部屬性既有基本類型，也有自定義的對象
定義一個 Body 類，里面有身高體重屬性，定義一個 Person 類，里面有基本信息和一個 Body 類型的屬性。
Body 類：
@Data
@AutoMapMapper
public class Body {
private int height;
private int weight;
}
Person 類：
@Data
@AutoMapMapper
public class Person {
private String name;
private Integer age;
private Body body;
}
3. 轉(zhuǎn)換測試
@SpringBootTest
public class MapToObjectTest {
@Autowired
private Converter converter;
@Test
public void test() {
// 創(chuàng)建一個 Map，鍵是 Body 的屬性名，值是屬性值
Map<String, Object> map1 = new HashMap<>();
map1.put("height", 180);
map1.put("weight", 150);
// 創(chuàng)建第二個 Map，鍵是 Person 的屬性名，值是屬性值
Map<String, Object> map2 = new HashMap<>();
map2.put("name", "wen");
map2.put("age", 18);
map2.put("body", map1);
// 將 Map2 轉(zhuǎn)化為 Person 對象
Person person = converter.convert(map2, Person.class);
System.out.println(person);
}
}
測試成功，Map 對象成功轉(zhuǎn)化為 Person 對象：
五、枚舉類型轉(zhuǎn)換
枚舉類型的轉(zhuǎn)換，需要在枚舉類上添加 @AutoEnumMapper 注解，增加該注解后，在任意類型中需要轉(zhuǎn)換該枚舉時都可以自動轉(zhuǎn)換。
使用 @AutoEnumMapper 注解的時候，需要注意：這個枚舉類必須要有一個可以保證唯一的字段，并將該字段添加到注解的 value屬性中
1. 定義一個枚舉類
定義一個狀態(tài)枚舉類，唯一字段是 code，用來表示開始還是關(guān)閉：
@Getter
@AllArgsConstructor
@AutoEnumMapper("code")
public enum StateEnum {
ENABLE(1, "啟用"),
DISABLE(0, "禁用");
private final int code;
private final String desc;
}
2. 定義要轉(zhuǎn)換的對象
定義一個保存枚舉類的類 Course，再定義一個需要轉(zhuǎn)換的 CourseVo 類：
Course 類：
@Data
@AutoMapper(target = CourseVo.class)
public class Course {
private StateEnum state;
}
CourseVo 類:
@Data
public class CourseVo {
private Integer state;
}
3. 轉(zhuǎn)換測試
@SpringBootTest
public class EnumToValueTest {
@Autowired
private Converter converter;
@Test
public void test() {
// 創(chuàng)建一個 Course 對象
Course course = new Course();
course.setState(StateEnum.ENABLE);
// 將 Course 對象轉(zhuǎn)換為 CourseVo 對象
CourseVo courseVo = converter.convert(course, CourseVo.class);
System.out.println(courseVo);
// 將 CourseVo 對象轉(zhuǎn)換為 Course 對象
Course course1 = converter.convert(courseVo, Course.class);
System.out.println(course1);
}
}
測試成功，Enum 可以轉(zhuǎn)化為整形，整形也可以轉(zhuǎn)化為 Enum：
4. 注意
枚舉和使用枚舉的類需要在同一個模塊（module）中。
當(dāng)枚舉與要使用的類型，不在同一個模塊中，是不能自動轉(zhuǎn)換的，需要指定依賴關(guān)系。在 @AutoMapper 注解中，可以通過 useEnums 來指定需要依賴的枚舉類列表。
六、一個類與多個類之間的轉(zhuǎn)換
MapStruct Plus 還支持一個類和多個類進(jìn)行轉(zhuǎn)換，可以通過 @AutoMappers 來配置，該注解支持配置多個 @AutoMapper。
在配置多個類進(jìn)行轉(zhuǎn)化的時候，多個類可能有相同的屬性，為了解決屬性沖突的問題，可以使用 @AutoMappings 指定多個轉(zhuǎn)換規(guī)則，并且在使用 @AutoMapping 注解時，配置 targetClass 屬性，指定當(dāng)前規(guī)則的目標(biāo)轉(zhuǎn)化類。
如果配置 @AutoMapping 注解時，沒有指定 targetClass，那么當(dāng)前規(guī)則就會應(yīng)用所有類轉(zhuǎn)換。
1. 定義對象
定義一個 User 類，一個 Course 類，一個 UserVo 類。其中 UserVo 類將與 User 類和 Course 類互相映射（UserVo 《===》User、Course）。User 類和 Course 類都有 name 屬性，但是只將 User 類中的 name 屬性映射。
User 類：
@Data
@AutoMapper(target = UserVo.class, uses = StringToListConverter.class)
public class User {
private String name;
private int age;
private String password;
@AutoMapping(target = "tagList")
private String tags;
}
Course 類：
@Data
@AutoMapper(target = UserVo.class)
public class Course {
@AutoMapping(targetClass = UserVo.class, ignore = true) // 忽略 UserVo 中的 name 屬性
private String name;
private String teacher;
}
UserVo 類：
@Data
@AutoMappers({
@AutoMapper(target = User.class, uses = ListToStringConverter.class),
@AutoMapper(target = Course.class)
})
public class UserVo {
@AutoMappings({
@AutoMapping(targetClass = User.class),
@AutoMapping(targetClass = Course.class, ignore = true)
})
private String name;
private int age;
@AutoMapping(targetClass = User.class, target = "tags")
private List<String> tagList;
private String teacher;
}
2. 轉(zhuǎn)換測試
@SpringBootTest
public class OneToOthersTest {
@Autowired
private Converter converter;
@Test
public void test() {
// 創(chuàng)建 User 對象
User user = new User();
user.setName("wen");
user.setAge(18);
user.setPassword("123456");
user.setTags("Java,Python,Go,C++");
// 創(chuàng)建 Course 對象
Course course = new Course();
course.setName("Java 開發(fā)");
course.setTeacher("教 Java 的老師");
// 轉(zhuǎn)換（User 對象和 Course 對象）為 UserVo 對象
UserVo userVo = converter.convert(user, UserVo.class);
userVo = converter.convert(course, userVo);
System.out.println(userVo);
// 轉(zhuǎn)換 UserVo 對象為（User 對象和 Course 對象）
user = converter.convert(userVo, User.class);
course = converter.convert(userVo, Course.class);
System.out.println(user);
System.out.println(course);
}
}
3. 測試結(jié)果
總結(jié)
本文使用大量示例詳細(xì)解釋了在 Spring Boot 項目開發(fā)中使用 MapStruct Plus 的方法，多加練習(xí)熟能生巧。技術(shù)沒有高低之分，不管是使用原始的 getter/setter 方法，還是使用 BeanUtils，亦或者使用本文所介紹的 MapStruct Plus，只要找到解決問題的合適方案就可以。
到此這篇關(guān)于MapStruct Plus的使用教程的文章就介紹到這了,更多相關(guān)MapStruct Plus內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！
相關(guān)文章
解決@Autowired報錯Could not autowire. No bea
介紹了在IDEA中使用@Autowired報錯Couldnot autowire. No beans of 'XXX' type found的解決方法,原因是@Autowired在注入service時,由于service接口沒有實現(xiàn)類,而mybatis僅需提供Dao接口,導(dǎo)致@Autowired無法識別2024-12-12
在程序設(shè)計中,進(jìn)行異常處理是非常關(guān)鍵和重要的一部分,一個程序的異常處理框架的好壞直接影響到整個項目的代碼質(zhì)量以及后期維護(hù)成本和難度,這篇文章主要給大家介紹了關(guān)于Java異常類型以及處理的相關(guān)資料,需要的朋友可以參考下2021-07-07
MyBatis是支持普通SQL查詢，存儲過程和高級映射的優(yōu)秀持久層框架。MyBatis消除了幾乎所有的JDBC代碼和參數(shù)的手工設(shè)置以及結(jié)果集的檢索。想要學(xué)好它，那就要從MyBatis基礎(chǔ)知識學(xué)起，下面跟著小編一起來看下吧2017-03-03
這篇文章主要介紹了微信公眾號獲取access_token的方法,結(jié)合實例形式分析了java實現(xiàn)微信公眾號獲取access_token的相關(guān)原理、實現(xiàn)方法及操作注意事項,需要的朋友可以參考下2019-10-10
這篇文章主要介紹了Java 對稱加密使用DES / 3DES / AES 這三種算法分別實現(xiàn)的相關(guān)資料,這里提供了實例代碼，需要的朋友可以參考下2017-01-01
這篇文章主要介紹了feign 獲取請求真實目的ip地址操作，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2021-06-06
Lombok項目是一個java庫，它可以自動插入到編輯器和構(gòu)建工具中，本文將詳細(xì)給大家介紹idea中的lombok不生效的四種解決方法,需要的朋友可以參考下2023-05-05
這篇文章主要介紹了SpringBoot中熔斷器的原理和使用詳解,熔斷器是一種用于處理分布式系統(tǒng)中故障的設(shè)計模式，它可以防止出現(xiàn)故障的服務(wù)對整個系統(tǒng)造成連鎖反應(yīng),需要的朋友可以參考下2023-07-07
這篇文章主要介紹了Java中的LinkedHashSet解析,與HashSet不同的是,LinkedHashSet在內(nèi)部使用了一個雙向鏈表來維護(hù)元素的順序,因此它可以保持元素的插入順序,這使得LinkedHashSet在需要保持元素順序的場景下非常有用,需要的朋友可以參考下2023-11-11
這篇文章主要介紹了Java三種移位運算符原理解析,文中通過示例代碼介紹的非常詳細(xì)，對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值,需要的朋友可以參考下2020-02-02