物件拷貝 - 優雅的解決方案 Mapstruct
阿新 • • 發佈：2019-05-30
MapStruct GitHub 訪問地址 : https://github.com/mapstruct/mapstruct/
使用例子 : https://github.com/mapstruct/mapstruct-examples
MapStrcut與其它工具對比以及使用說明! http://www.tuicool.com/articles/uiIRjai
- 是否一直在使用BeanUtils.copyProperties 用於物件屬性拷貝。 出現種種小問題。
- 會將同名屬性拷貝到另外一個物件中，操作方便但是存在一個缺陷 （速度慢）
- 有些同名欄位卻無法進行特殊化處理，將會導致不想修改的欄位被覆蓋。也不能自定義屬性對映
- 有些同名欄位卻無法進行特殊化處理，將會導致不想修改的欄位被覆蓋。也不能自定義屬性對映
在 mvc層 我們經常會DTO物件返回給前端 進行欄位渲染。我們不喜歡將所有欄位都顯示給前端，或者我們需要修改欄位返回給前端，例如 資料中儲存的上架下架是0，1 但是前端需要的欄位是true 和 false。 我們都得進行手動判斷處理然後編輯成DTO返回給前端
MapStruct是一種型別安全的bean對映類生成java註釋處理器。
我們要做的就是定義一個對映器介面，宣告任何必需的對映方法。在編譯的過程中，MapStruct會生成此介面的實現。該實現使用純java方法呼叫的源和目標物件之間的對映，MapStruct節省了時間，通過生成程式碼完成繁瑣和容易出錯的程式碼邏輯。。
- MapStruct 擁有的優點：
- 使用普通方法呼叫而不是反射來快速執行，他會在編譯器生成相應的 Impl 方法呼叫時直接通過簡單的 getter/setter呼叫而不是反射或類似的方式將值從源複製到目標
- 編譯時型別安全性 : 只能對映彼此的物件和屬性，不能將商品實體意外對映到使用者 DTO等
- 在構建時清除錯誤報告，如 對映不完整 (並非所有目標屬性都被對映) 或 對映不正確(無法找到適當的對映方法或型別轉換)
- MapStruct 提供的重要註解 :
- @Mapper : 標記這個介面作為一個對映介面，並且是編譯時 MapStruct 處理器的入口
- @Mapping : 解決源物件和目標物件中，屬性名字不同的情況
- Mappers.getMapper 自動生成的介面的實現可以通過 Mapper 的 class物件獲取，從而讓客戶端可以訪問 Mapper介面的實現
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0http://maven.apache.org/xsd/maven-4.0.0.xsd">
<properties>
// ...
<org.mapstruct.version>1.2.0.Final</org.mapstruct.version>
</properties>
<dependencies>
...
<!-- MapStruct START -->
<dependency>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-jdk8</artifactId>
<version>${org.mapstruct.version}</version>
</dependency>
<dependency>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-processor</artifactId>
<version>${org.mapstruct.version}</version>
</dependency>
<!-- MapStruct END -->
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.5.1</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
<annotationProcessorPaths>
<path>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-processor</artifactId>
<version>${org.mapstruct.version}</version>
</path>
</annotationProcessorPaths>
<compilerArgs>
<compilerArg>-Amapstruct.defaultComponentModel=spring</compilerArg>
<compilerArg>-Amapstruct.suppressGeneratorTimestamp=true</compilerArg>
<compilerArg>-Amapstruct.suppressGeneratorVersionInfoComment=true</compilerArg>
</compilerArgs>
</configuration>
</plugin>
</plugins>
</build>
</project>- BasicObjectMapper包含了4個基本方法，單個和集合以及反轉的單個和集合。開發中如需要物件轉換操作可直接新建 interface 並繼承 BasicObjectMapper，並在新建的介面上加上 @Mapper(componentModel = "spring")，如果是屬性中包含其它類以及該類已經存在 Mapper 則註解中加上 users = {類名.class}。componentModel = "spring" 該配置表示生成的實現類預設加上 spring @Component 註解，使用時可直接通過 @Autowire 進行注入
public interface BasicObjectMapper<SOURCE, TARGET> {
@Mappings({})
@InheritConfiguration
TARGET to(SOURCE var1);
@InheritConfiguration
List<TARGET> to(List<SOURCE> var1);
@InheritInverseConfiguration
SOURCE from(TARGET var1);
@InheritInverseConfiguration
List<SOURCE> from(List<TARGET> var1);
}
- 直接使用進行物件資料轉換
@Data
public class ProductCategory {
/** 類別編碼 */
private String categoryCode;
/** 類別名稱 */
private String categoryName;
}
@Data
public class CategoryVo {
private String code;
private String name;
}
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.Mappings;
import org.mapstruct.factory.Mappers;
@Mapper
public interface CategoryMapper extends BasicObjectMapper<CategoryVo, ProductCategory> {
CategoryMapper MAPPER = Mappers.getMapper(CategoryMapper.class);
@Mappings({
@Mapping(source = "code", target = "categoryCode"),
@Mapping(source = "name", target = "categoryName")
})
ProductCategory to(CategoryVo source);
}
public static void main(String[] args) {
CategoryMapper categoryMapper = CategoryMapper.MAPPER;
CategoryVo vo = new CategoryVo();
vo.setCode("0000");
vo.setName("屬性名稱");
ProductCategory pc = categoryMapper.to(vo); // 通過 to方法得到 ProductCategory
System.out.println("1" + pc);
CategoryVo vo1 = categoryMapper.from(pc); // 通過 from方法得到 CategoryVo，既反轉 to方法
System.out.println("2" + vo1);
List<ProductCategory> pcList = categoryMapper.to(Arrays.asList(vo, vo1)); // 通過to方法從集合得到轉換後的集合
System.out.println("3" + pcList);
List<CategoryVo> voList = categoryMapper.from(pcList); // 反轉集合
System.out.println("4" + voList);
}
- 自定義方法新增到對映器 : 在某些情況下，需要手動實現 MapStruct 無法生成的從一種型別到另一種型別的特定對映，有如下兩種實現方法 :
- 方法1> 在另一個類上實現此類方法，然後由 MapStruct 生成的對映器使用該方法
- 方法2> 在Java 8或更高版本時，可以直接在對映器介面中實現自定義方法作為預設方法。如果引數和返回型別匹配，生成的程式碼將呼叫預設方法
@Mapper
public interface CarMapper {
CarMapper MAPPER = Mappers.getMapper(CarMapper.class);
@Mappings({...})
CarDto carToCarDto(Car car);
default PersonDto personToPersonDto(Person person) {
// hand-written mapping logic
}
}- 對映器也可以定義為抽象類的形式而不是介面，並直接在此對映器類中實現自定義方法。在這種情況下，MapStruct將生成抽象類的擴充套件，並實現所有抽象方法。這種方法優於宣告預設方法的優點是可以在對映器類中宣告附加欄位
@Mapper
public abstract class CarMapper {
@Mappings(...)
public abstract CarDto carToCarDto(Car car);
public PersonDto personToPersonDto(Person person) {
// hand-written mapping logic
}
}- 多源引數對映方法 : MapStruct 支援多個源引數的對映方法，將幾個實體組合成一個數據傳輸物件
@Mapper
public interface AddressMapper {
@Mappings({
@Mapping(source = "person.description", target = "description"),
@Mapping(source = "address.houseNo", target = "houseNumber")
})
DeliveryAddressDto personAndAddressToDeliveryAddressDto(Person person, Address address);
}- 如果多個源物件定義了一個具有相同名稱的屬性，則必須使用 @Mapping 註釋來指定從中檢索屬性的源引數，如果這種歧義未得到解決，將會引發錯誤。對於在給定源物件中只存在一次的屬性，指定源引數的名稱是可選的，因為它可以自動確定
MapStruct 還提供直接引用源引數
@Mapper
public interface AddressMapper {
@Mappings({
@Mapping(source = "person.description", target = "description"),
@Mapping(source = "hn", target = "houseNumber")
})
DeliveryAddressDto personAndAddressToDeliveryAddressDto(Person person, Integer hn);
}
- 直接欄位訪問對映 : MapStruct 支援 public 沒有 getter/setter 的欄位的對映，如果 MapStruct 無法為屬性找到合適的 getter/setter方法，MapStruct 將使用這些欄位作為 讀/寫訪問器。如果它是 public，則欄位被認為是讀取存取器 public final。如果一個欄位 static 不被視為讀取存取器只有在欄位被認為是寫入訪問者的情況下 public。如果一個欄位 final 和/或 static 它不被認為是寫入訪問者
public class Customer {
private Long id;
private String name;
// getters and setter omitted for brevity
}
public class CustomerDto {
public Long id;
public String customerName;
}
@Mapper
public interface CustomerMapper {
CustomerMapper MAPPER = Mappers.getMapper( CustomerMapper.class );
@Mapping(source = "customerName", target = "name")
Customer toCustomer(CustomerDto customerDto);
@InheritInverseConfiguration
CustomerDto fromCustomer(Customer customer);
}
// 生成的對映器如下
public class CustomerMapperImpl implements CustomerMapper {
@Override
public Customer toCustomer(CustomerDto customerDto) {
// ...
customer.setId( customerDto.id );
customer.setName( customerDto.customerName );
// ...
}
@Override
public CustomerDto fromCustomer(Customer customer) {
// ...
customerDto.id = customer.getId();
customerDto.customerName = customer.getName();
// ...
}
}
- 檢索對映器 : Mapper例項 通過 org.mapstruct.factory.Mappers 的 getMapper() 方法來檢索。通常 對映器介面應該定義一個名為的成員 INSTANCE ，它包含一個對映器型別的單個例項 :
@Mapper
public interface CarMapper {
CarMapper INSTANCE = Mappers.getMapper(CarMapper.class);
CarDto carToCarDto(Car car);
}
這種模式使客戶非常容易地使用對映器物件，而無需反覆例項化新的例項 :
Car car = ...;
CarDto dto = CarMapper.INSTANCE.carToCarDto( car );
使用依賴注入 : 通過 Spring 依賴注入可以獲取對映器物件
@Mapper(componentModel = "spring")
public interface CarMapper {
CarDto carToCarDto(Car car);
}
@Inject
private CarMapper mapper;- 資料型別轉換 : 源物件和目標物件中對映的屬性型別可能不同，MapStruct 提供自動處理型別轉換，提供如下自動轉換 :
- 1> Java基本資料型別及其相應的包裝型別，如 int 和 Integer，boolean 和 Boolean 等生成的程式碼是 null 轉換一個包裝型成相應的原始型別時一個感知，即 null 檢查將被執行
- 2> Java基本號碼型別和包裝型別，例如之間 int 和 long 或 byte 和 Integer (大類型別資料轉換成小類可能出現精度損失)
- 3> 所有Java基本型別之間 (包括其包裝) 和 String 之間，例如 int 和 String 或 Boolean 和 String，java.text.DecimalFormat 均可以指定格式字串
- int 到 String的轉換
int 到 String的轉換
@Mapper
public interface CarMapper {
@Mapping(source = "price", numberFormat = "$#.00")
CarDto carToCarDto(Car car);
@IterableMapping(numberFormat = "$#.00")
List<String> prices(List<Integer> prices);
}
BigDecimal 轉換為 String
@Mapper
public interface CarMapper {
@Mapping(source = "power", numberFormat = "#.##E0")
CarDto carToCarDto(Car car);
}
從日期到字串的轉換
@Mapper
public interface CarMapper {
@Mapping(source = "manufacturingDate", dateFormat = "dd.MM.yyyy")
CarDto carToCarDto(Car car);
@IterableMapping(dateFormat = "dd.MM.yyyy")
List<String> stringListToDateList(List<Date> dates);
}
對映物件引用 : 物件中如果包含另一個物件的引用，此時只需為引用的物件型別定義對映方法即可
@Mapper
public interface CarMapper {
CarDto carToCarDto(Car car);
PersonDto personToPersonDto(Person person);
}
# 對映器控制巢狀的bean對映
@Mapper
public interface FishTankMapper {
@Mappings({
@Mapping(target = "fish.kind", source = "fish.type"),
@Mapping(target = "fish.name", ignore = true),
@Mapping(target = "plant", ignore = true ),
@Mapping(target = "ornament", ignore = true ),
@Mapping(target = "material", ignore = true),
@Mapping(target = "ornament", source = "interior.ornament"),
@Mapping(target = "material.materialType", source = "material"),
@Mapping(target = "quality.report.organisation.name", source = "quality.report.organisationName")
})
FishTankDto map( FishTank source );
}
- 呼叫其他對映器 : MapStruct 中可以呼叫在其他類中定義的對映方法，無論是由MapStruct生成的對映器還是手寫對映方法
# 手動實現的對映
public class DateMapper {
public String asString(Date date) {
return date != null ? new SimpleDateFormat("yyyy-MM-dd").format(date) : null;
}
public Date asDate(String date) {
try {
return date != null ? new SimpleDateFormat("yyyy-MM-dd").parse(date) : null;
} catch (ParseException e) {
throw new RuntimeException(e);
}
}
}
# 引用另一個對映器類
@Mapper(uses = DateMapper.class)
public class CarMapper {
CarDto carToCarDto(Car car);
}
- 當為該 carToCarDto() 方法的實現生成程式碼時，MapStruct將查詢將 Date 物件對映到String的方法，在 DateMapper 該類上找到它並生成 asString() 用於對映該 manufacturingDate 屬性的呼叫
- 對映集合 : 集合型別(對映 List，Set 等等) 以相同的方式對映 bean型別，通過定義與在對映器介面所需的源和目標型別的對映方法。生成的程式碼將包含一個遍歷源集合的迴圈，轉換每個元素並將其放入目標集合中。如果在給定的對映器或其使用的對映器中找到了集合元素型別的對映方法，則會呼叫此方法以執行元素轉換。或者，如果存在源和目標元素型別的隱式轉換，則將呼叫此轉換例程
@Mapper
public interface CarMapper {
Set<String> integerSetToStringSet(Set<Integer> integers);
List<CarDto> carsToCarDtos(List<Car> cars);
CarDto carToCarDto(Car car);
}
# 生成的集合對映方法
@Override
public Set<String> integerSetToStringSet(Set<Integer> integers) {
if (integers == null) {
return null;
}
Set<String> set = new HashSet<>();
for (Integer integer : integers) {
set.add(String.valueOf(integer));
}
return set;
}
@Override
public List<CarDto> carsToCarDtos(List<Car> cars) {
if (cars == null) {
return null;
}
List<CarDto> list = new ArrayList<>();
for (Car car : cars) {
list.add(carToCarDto(car));
}
return list;
}
對映Map :
public interface SourceTargetMapper {
@MapMapping(valueDateFormat = "dd.MM.yyyy")
Map<String, String> longDateMapToStringStringMap(Map<Long, Date> source);
}
對映流 :
@Mapper
public interface CarMapper {
Set<String> integerStreamToStringSet(Stream<Integer> integers);
List<CarDto> carsToCarDtos(Stream<Car> cars);
CarDto carToCarDto(Car car);
}
- 對映列舉 : 預設情況下，源列舉中的每個常量對映到目標列舉型別中具有相同名稱的常量。如果需要，可以使用 @ValueMapping 註釋幫助將source enum中的常量對映為具有其他名稱的常量
@Mapper
public interface OrderMapper {
OrderMapper INSTANCE = Mappers.getMapper(OrderMapper.class);
@ValueMappings({
@ValueMapping(source = "EXTRA", target = "SPECIAL"),
@ValueMapping(source = "STANDARD", target = "DEFAULT"),
@ValueMapping(source = "NORMAL", target = "DEFAULT")
})
ExternalOrderType orderTypeToExternalOrderType(OrderType orderType);
}
預設值和常量 :
@Mapper(uses = StringListMapper.class)
public interface SourceTargetMapper {
SourceTargetMapper INSTANCE = Mappers.getMapper(SourceTargetMapper.class);
@Mappings({
@Mapping(target = "stringProperty", source = "stringProp", defaultValue = "undefined"),
@Mapping(target = "longProperty", source = "longProp", defaultValue = "-1"),
@Mapping(target = "stringConstant", constant = "Constant Value"),
@Mapping(target = "integerConstant", constant = "14"),
@Mapping(target = "longWrapperConstant", constant = "3001"),
@Mapping(target = "dateConstant", dateFormat = "dd-MM-yyyy", constant = "09-01-2014"),
@Mapping(target = "stringListConstants", constant = "jack-jill-tom")
})
Target sourceToTarget(Source s);
}
表示式 :
@Mapper
public interface SourceTargetMapper {
SourceTargetMapper INSTANCE = Mappers.getMapper(SourceTargetMapper.class);
@Mapping(target = "timeAndFormat", expression = "java( new org.sample.TimeAndFormat( s.getTime(), s.getFormat() ) )")
Target sourceToTarget(Source s);
}- 確定結果型別 : 當結果型別具有繼承關係時，選擇對映方法(@Mapping) 或工廠方法(@BeanMapping) 可能變得不明確。假設一個Apple和一個香蕉，這兩個都是 Fruit的專業
@Mapper(uses = FruitFactory.class)
public interface FruitMapper {
@BeanMapping(resultType = Apple.class)
Fruit map(FruitDto source);
}
public class FruitFactory {
public Apple createApple() {
return new Apple("Apple");
}
public Banana createBanana() {
return new Banana("Banana");
}
}- 控制 '空' 引數的對映結果 : 預設情況下 null 會返回，通過指定 nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT 上 @BeanMapping，@IterableMapping，@MapMapping，或全域性上 @Mapper 或 @MappingConfig，對映結果可以被改變以返回空預設值
- 1> Bean對映 : 將返回一個 '空' 目標bean，除常量和表示式外，它們將在存在時填充
- 2> 基元 : 基元的預設值將被返回，例如 false for boolean 或 0 for int
- 3> Iterables/Arrays : 一個空的迭代器將被返回
- 4> 地圖 : 將返回空白地圖
- 共享配置 : 通過指向中心介面來定義共享配置的可能性 @MapperConfig，要使對映器使用共享配置，需要在 @Mapper#config 屬性中定義配置介面。該 @MapperConfig 註釋具有相同的屬性 @Mapper 註釋。任何未通過的屬性 @Mapper 都將從共享配置繼承。指定 @Mapper 的屬性優先於通過引用的配置類指定的屬性
@MapperConfig(uses = CustomMapperViaMapperConfig.class, unmappedTargetPolicy = ReportingPolicy.ERROR)
public interface CentralConfig {}
@Mapper(config = CentralConfig.class, uses = { CustomMapperViaMapper.class } )
public interface SourceTargetMapper {}本文作者：雲楊四海
原文連結：物件拷貝 - 優雅的解決方案 Mapstruct
版權歸作者所有，轉載請註明出處