mapStruct java bean對映工具（1）
阿新 • • 發佈：2019-08-04
在一個成熟的工程中，尤其是現在的分散式系統中，應用與應用之間，還有單獨的應用細分模組之後，DO 一般不會讓外部依賴，這時候需要在提供對外介面的模組裡放 DTO 用於物件傳輸，也即是 DO 物件對內，DTO物件對外，DTO 可以根據業務需要變更，並不需要對映 DO 的全部屬性。
這種 物件與物件之間的互相轉換，就需要有一個專門用來解決轉換問題的工具，畢竟每一個欄位都 get/set 會很麻煩。
MapStruct 就是這樣的一個屬性對映工具，只需要定義一個 Mapper 介面，MapStruct 就會自動實現這個對映介面，避免了複雜繁瑣的對映實現。
一、工程中引入 maven 依賴
<properties> <mapstruct.version>1.2.0.Final</mapstruct.version> </properties> <dependencies> <dependency> <groupId>org.mapstruct</groupId> <artifactId>mapstruct-jdk8</artifactId> <version>${mapstruct.version}</version> </dependency> <dependency> <groupId>org.mapstruct</groupId> <artifactId>mapstruct-processor</artifactId> <version>${mapstruct.version}</version> </dependency> </dependencies>
二、基本對映
這裡定義兩個 DO 物件 Person 和 User，其中 user 是 Person 的一個屬性 ，一個 DTO 物件 PersonDTO。
JavaBean：
@NoArgsConstructor @AllArgsConstructor @Data public class Person { private Long id; private String name; private String email; private Date birthday; private User user; } @NoArgsConstructor @AllArgsConstructor @Data public class User { private Integer age; } @NoArgsConstructor @AllArgsConstructor @Data public class PersonDTO { private Long id; private String name; /** * 對應 Person.user.age */ private Integer age; private String email; /** * 與 DO 裡面的欄位名稱(birthDay)不一致 */ private Date birth; /** * 對 DO 裡面的欄位(birthDay)進行拓展,dateFormat 的形式 */ private String birthDateFormat; /** * 對 DO 裡面的欄位(birthDay)進行拓展,expression 的形式 */ private String birthExpressionFormat; }
寫一個 Mapper 介面 PersonConverter，其中兩個方法，一個是單實體對映，另一個是List對映。
若源物件屬性與目標物件屬性名字一致，會自動對映對應屬性，不一樣的需要指定，也可以用 format 轉成自己想要的型別，也支援表示式的方式，可以看到像 id、name、email這些名詞一致的我並沒有指定 source-target，而birthday-birth指定了，轉換格式的 birthDateFormat 加了dateFormat 或者 birthExpressionFormat 加了 expression，如果某個屬性你不想對映，可以加個 ignore=true。
MapSruct的Mapper（對映類）：
@Mapper
public interface PersonConverter {
PersonConverter INSTANCE = Mappers.getMapper(PersonConverter.class);
@Mappings({
@Mapping(source = "birthday", target = "birth"),
@Mapping(source = "birthday", target = "birthDateFormat", dateFormat = "yyyy-MM-dd HH:mm:ss"),
@Mapping(target = "birthExpressionFormat", expression = "java(org.apache.commons.lang3.time.DateFormatUtils.format(person.getBirthday(),\"yyyy-MM-dd HH:mm:ss\"))"),
@Mapping(source = "user.age", target = "age"),
@Mapping(target = "email", ignore = true)
})
PersonDTO domain2dto(Person person);
List<PersonDTO> domain2dto(List<Person> people);
}
編譯MapStruct之後，手工編譯或者啟動 IDE 的時候 IDE 也會幫我們編譯， 會自動在 target/classes 下生成對應的實現類。
手工編譯命令
mvn compile
注意！！！下面這個 PersonConverterImpl 是自動生成的，不是自己寫的！
public class PersonConverterImpl implements PersonConverter {
public PersonConverterImpl() {
}
public PersonDTO domain2dto(Person person) {
if (person == null) {
return null;
} else {
PersonDTO personDTO = new PersonDTO();
personDTO.setBirth(person.getBirthday());
if (person.getBirthday() != null) {
personDTO.setBirthDateFormat((new SimpleDateFormat("yyyy-MM-dd HH:mm:ss")).format(person.getBirthday()));
}
Integer age = this.personUserAge(person);
if (age != null) {
personDTO.setAge(age);
}
personDTO.setId(person.getId());
personDTO.setName(person.getName());
personDTO.setBirthExpressionFormat(DateFormatUtils.format(person.getBirthday(), "yyyy-MM-dd HH:mm:ss"));
return personDTO;
}
}
public List<PersonDTO> domain2dto(List<Person> people) {
if (people == null) {
return null;
} else {
List<PersonDTO> list = new ArrayList(people.size());
Iterator var3 = people.iterator();
while(var3.hasNext()) {
Person person = (Person)var3.next();
list.add(this.domain2dto(person));
}
return list;
}
}
private Integer personUserAge(Person person) {
if (person == null) {
return null;
} else {
User user = person.getUser();
if (user == null) {
return null;
} else {
Integer age = user.getAge();
return age == null ? null : age;
}
}
}
}
寫一個單元測試類 PersonConverterTest 測試一下，看看效果。
public class PersonConverterTest {
@Test
public void test() {
Person person = new Person(1L,"zhige","[email protected]",new Date(),new User(1));
PersonDTO personDTO = PersonConverter.INSTANCE.domain2dto(person);
assertNotNull(personDTO);
assertEquals(personDTO.getId(), person.getId());
assertEquals(personDTO.getName(), person.getName());
assertEquals(personDTO.getBirth(), person.getBirthday());
String format = DateFormatUtils.format(personDTO.getBirth(), "yyyy-MM-dd HH:mm:ss");
assertEquals(personDTO.getBirthDateFormat(),format);
assertEquals(personDTO.getBirthExpressionFormat(),format);
List<Person> people = new ArrayList<>();
people.add(person);
List<PersonDTO> personDTOs = PersonConverter.INSTANCE.domain2dto(people);
assertNotNull(personDTOs);
}
}
三、多對一
MapStruct 可以將幾種型別的物件對映為另外一種型別，比如將多個 DO 物件轉換為 DTO。
例子：
- 兩個 DO 物件 Item 和 Sku，一個 DTO 物件 SkuDTO
@NoArgsConstructor
@AllArgsConstructor
@Data
public class Item {
private Long id;
private String title;
}
@NoArgsConstructor
@AllArgsConstructor
@Data
public class Sku {
private Long id;
private String code;
private Integer price;
}
@NoArgsConstructor
@AllArgsConstructor
@Data
public class SkuDTO {
private Long skuId;
private String skuCode;
private Integer skuPrice;
private Long itemId;
private String itemName;
}
- 建立 ItemConverter（對映）介面，MapStruct 就會自動實現該介面。
@Mapper
public interface ItemConverter {
ItemConverter INSTANCE = Mappers.getMapper(ItemConverter.class);
@Mappings({
@Mapping(source = "sku.id",target = "skuId"),
@Mapping(source = "sku.code",target = "skuCode"),
@Mapping(source = "sku.price",target = "skuPrice"),
@Mapping(source = "item.id",target = "itemId"),
@Mapping(source = "item.title",target = "itemName")
})
SkuDTO domain2dto(Item item, Sku sku);
}
- 建立測試類，講 Item 和 Sku 兩個 DO物件，對映成一個 DTO 物件 SkuDTO
public class ItemConverterTest {
@Test
public void test() {
Item item = new Item(1L, "iPhone X");
Sku sku = new Sku(2L, "phone12345", 1000000);
SkuDTO skuDTO = ItemConverter.INSTANCE.domain2dto(item, sku);
assertNotNull(skuDTO);
assertEquals(skuDTO.getSkuId(),sku.getId());
assertEquals(skuDTO.getSkuCode(),sku.getCode());
assertEquals(skuDTO.getSkuPrice(),sku.getPrice());
assertEquals(skuDTO.getItemId(),item.getId());
assertEquals(skuDTO.getItemName(),item.getTitle());
}
}
四、可以新增自定義方法
// 形式如下
default PersonDTO personToPersonDTO(Person person) {
//hand-written mapping logic
}
// 比如在 PersonConverter 裡面加入如下
default Boolean convert2Bool(Integer value) {
if (value == null || value < 1) {
return Boolean.FALSE;
} else {
return Boolean.TRUE;
}
}
default Integer convert2Int(Boolean value) {
if (value == null) {
return null;
}
if (Boolean.TRUE.equals(value)) {
return 1;
}
return 0;
}
// 測試類 PersonConverterTest 加入
assertTrue(PersonConverter.INSTANCE.convert2Bool(1));
assertEquals((int)PersonConverter.INSTANCE.convert2Int(true),1);
五、Spring 注入的方式
// 剛才一直寫的例子是預設的方式
PersonConverter INSTANCE = Mappers.getMapper(PersonConverter.class);
還有一種常用的方式，是和常用的框架 Spring 結合，在 @Mapper 後面加入 componentModel="spring"。
@Mapper(componentModel="spring")
public interface PersonConverter {
@Mappings({
@Mapping(source = "birthday", target = "birth"),
@Mapping(source = "birthday", target = "birthDateFormat", dateFormat = "yyyy-MM-dd HH:mm:ss"),
@Mapping(target = "birthExpressionFormat", expression = "java(org.apache.commons.lang3.time.DateFormatUtils.format(person.getBirthday(),\"yyyy-MM-dd HH:mm:ss\"))"),
@Mapping(source = "user.age", target = "age"),
@Mapping(target = "email", ignore = true)
})
PersonDTO domain2dto(Person person);
}
這時候測試類改一下，我用的 spring boot 的形式。
@RunWith(SpringRunner.class)
@SpringBootTest(classes = BaseTestConfiguration.class)
public class PersonConverterTest {
//這裡把轉換器裝配進來
@Autowired
private PersonConverter personConverter;
@Test
public void test() {
Person person = new Person(1L,"zhige","[email protected]",new Date(),new User(1));
PersonDTO personDTO = personConverter.domain2dto(person);
assertNotNull(personDTO);
assertEquals(personDTO.getId(), person.getId());
assertEquals(personDTO.getName(), person.getName());
assertEquals(personDTO.getBirth(), person.getBirthday());
String format = DateFormatUtils.format(personDTO.getBirth(), "yyyy-MM-dd HH:mm:ss");
assertEquals(personDTO.getBirthDateFormat(),format);
assertEquals(personDTO.getBirthExpressionFormat(),format);
}
}
六、MapStruct 註解的關鍵詞
@Mapper 只有在介面加上這個註解， MapStruct 才會去實現該介面
@Mapper 裡有個 componentModel 屬性，主要是指定實現類的型別，一般用到兩個
default：預設，可以通過 Mappers.getMapper(Class) 方式獲取例項物件
spring：在介面的實現類上自動添加註解 @Component，可通過 @Autowired 方式注入
@Mapping：屬性對映，若源物件屬性與目標物件名字一致，會自動對映對應屬性
source：源屬性
target：目標屬性
dateFormat：String 到 Date 日期之間相互轉換，通過 SimpleDateFormat，該值為 SimpleDateFormat 的日期格式
ignore: 忽略這個欄位
@Mappings：配置多個@Mapping
@MappingTarget 用於更新已有物件
@InheritConfiguration 用於