MapStruct 解了對象映射的毒

前言

MVC模式是目前主流項目的標準開發模式，這種模式下框架的分層結構清晰，主要分爲Controller，Service，Dao。分層的結構下，各層之間的數據傳輸要求就會存在差異，我們不能用一個對象來貫穿3層，這樣不符合開發規範且不夠靈活。

我們常常會遇到層級之間字段格式需求不一致的情況，例如數據庫中某個字段是datetime日期格式，這個時間戳在數據庫中的存儲值爲2020-11-06 23:59:59.999999，但是傳遞給前端的時候要求接口返回yyyy-MM-dd的格式，或者有些數據在數據庫中是逗號拼接的String類型，但是前端需要的是切割後的List類型等等。

所以我們提出了層級間的對象模型，就是我們常見的VO，DTO，DO，PO等等。這種區分層級對象模型的方式雖然清晰化了我們各層級間的對象傳遞，但是對象模型間的相互轉換和值拷貝確是讓人感覺很麻煩，拷貝來拷貝去，來來回回，過程重複乏味，編寫此類映射代碼是一項繁瑣且容易出錯的任務。

最簡單粗糙的拷貝方法就是不斷的new對象然後對象間的 setter 和 getter，這種方式應對字段屬性少的還可以，如果屬性字段很多那麼大段的set，get的代碼就顯得很不雅美。因此需要藉助對象拷貝工具，目前市場上的也蠻多的像BeanCopy，Dozer等等，但是這些我感覺都不夠好，今天我推薦一個實體映射工具就是 MapStruct。

介紹

MapStruct的官網地址是 https://mapstruct.org/MapStruct，是一個快速安全的bean 映射代碼生成器，只需要通過簡單的註解就可以實現對象間的屬性轉換，是一款 Apache LICENSE 2.0 授權的開源產品，Github的源碼地址是 https://github.com/mapstruct。

通過官網的三連問（What，Why，How）我們可以大概的瞭解到 MapStruct 的作用，它的優勢以及它是如何實現的。

從上面的三連問中我們可以得到如下信息：

• 基於約定優於配置的方法
  MapStruct 極大地簡化了 Java bean 類型之間的映射的實現，通過簡單的註解就可以工作。生成的映射代碼使用普通的方法調用而不是反射，因此速度快，類型安全且易於理解。

• 在編譯時生成 Bean 映射
  與其他映射框架相比，MapStruct 在編譯時生成 Bean 映射，這樣可以確保高性能，而且開發人員可以快速的得到反饋和徹底的錯誤檢查。

• 一個註釋處理器
  MapStruct 是一個註釋處理器，已插入 Java 編譯器，可用於命令行構建（Maven，Gradle等），也可用於您首選的IDE中（IDEA，Eclipse等）。

代碼編寫

MapStruct 需要 Java 1.8或更高版本。對於Maven-based 的項目，在pom 文件中添加如下依賴即可

<!-- 指定版本-->
<properties>
    <org.mapstruct.version>1.4.1.Final</org.mapstruct.version>
</properties>
<!-- 添加依賴 -->
<dependencies>
   <dependency>
	<groupId>org.mapstruct</groupId>
	<artifactId>mapstruct</artifactId>
	<version>${org.mapstruct.version}</version>
   </dependency>
   <dependency>
	<groupId>org.mapstruct</groupId>
	<artifactId>mapstruct-processor</artifactId>
	<version>${org.mapstruct.version}</version>
   </dependency>
</dependencies>

基本的依賴引入後就可以編寫代碼了，簡單的定義一個映射類，爲了與 Mybatis中的 mapper 接口區分，我們可以取名爲 xxObjectConverter。

例如汽車對象的映射類名爲 CarObjectConverter，我們有兩個對象模型 DO 和 DTO，它們內部的屬性字段如下：

數據庫對應的持久化對象模型 CarDo

public class Car {
    @ApiModelProperty(value = "主鍵id")
    private Long id;
	
    @ApiModelProperty(value = "製造商")
    private String manufacturers;
	
    @ApiModelProperty(value = "銷售渠道")
    private String saleChannel;

    @ApiModelProperty(value = "生產日期")
    private Date productionDate;
    ...
}

層級間傳輸的對象模型 CarDto

public class CarDto {
    @ApiModelProperty(value = "主鍵id")
    private Long id;
	
    @ApiModelProperty(value = "製造商")
    private String maker;
	
    @ApiModelProperty(value = "銷售渠道")
    private List<Integer> saleChannel;

    @ApiModelProperty(value = "生產日期")
    private Date productionDate;
    ...
}

再編寫具體的 MapStruct 對象映射器

@Mapper
public interface CarObjectConverter{

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

    @Mapping(target = "maker", source = "manufacturers")
    CarDto carToCarDto(Car car);

}

對於字段名相同的可以不用額外的指定映射規則，但是字段名不同的屬性則需要指出字段的映射規則，如上我們持久層 DO 的製造商的字段名是manufacturers 而層級間傳輸的DTO模型中則是maker，我們就需要在映射方法上通過@Mapping註解指出映射規則，我個人習慣是喜歡將target寫在前面，source寫在後面，這樣是與映射對象的位置保持一致，差異字段多的時候方便對比且不易混淆。

開發過程中還會經常遇到一些日期格式的轉換，就如開篇時說的那種，這時我們也可以指定日期的映射規則

@Mapper
public interface CarObjectConverter{

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

    @Mapping(target = "maker", source = "manufacturers")
    @Mapping(target = "productionDate", dateFormat = "yyyy-MM-dd", source = "productionDate")
    CarDto carToCarDto(Car car);

}

這些都還是一些簡單的字段的映射，但有時候我們兩個對象模型間的字段類型不一致，如上汽車的銷售渠道字段saleChannel，這個在數據庫中是字符串逗號拼接的值1,2,3，而我們傳遞出去的需要是 List 的 Integer 類型，這種複雜的如何映射呢？

也是有方法的，我們先編寫一個將字符串逗號分隔然後轉成 List 的工具方法，如下

public class CollectionUtils {

    public static List<Integer> list2String(String str) {
        if (StringUtils.isNoneBlank(str)) {
            return Arrays.asList(str.split(",")).stream().map(s -> Integer.valueOf(s.trim())).collect(Collectors.toList());
        }
        return null;
    }
}

然後在映射Mapping中使用表達式即可

@Mapper
public interface CarObjectConverter {

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

    @Mapping(target = "maker", source = "manufacturers")
    @Mapping(target = "productionDate", dateFormat = "yyyy-MM-dd", source = "productionDate")
    @Mapping(target = "saleChannel", expression = "java(com.jiajian.demo.utils.CollectionUtils.list2String(car.getSaleChannel()))")
    CarDto carToCarDto(Car car);

}

這樣就完成了所有字段的映射工作，我們在需要對象模型轉換的地方按照如下方式調用即可

CarDto carDto = CarObjectConverter.INSTANCE.carToCarDto(car);

這種是單體對象之間的 Copy 很多時候我們需要 List 對象模型間的轉換，只需要再寫一個方法carToCarDtos即可

@Mapper
public interface CarObjectConverter{

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

    @Mapping(target = "maker", source = "manufacturers")
    @Mapping(target = "productionDate", dateFormat = "yyyy-MM-dd", source = "productionDate")
    @Mapping(target ="saleChannel", expression = "java(com.jiajian.demo.utils.CollectionUtils.list2String(car.getSaleChannel()))")
    CarDto carToCarDto(Car car);

    List<CarDto> carToCarDtos(List<Car> carList);

}

探個究竟

會不會好奇這是怎麼實現的，我們只是創建了一個接口然後在接口方法上加一個註解並在註解裏面指定字段的映射規則就可以實現對象屬性間的拷貝，這是怎麼做到的呢？

我們這裏通過 MapStruct 創建的只是一個接口，要實現具體的功能接口必有實現。

MapStruct 會在我們代碼編譯的時候爲我們創建一個實現類，而這個實現類裏面通過字段的setter, getter方法來實現字段的賦值，從而實現對象的映射。

這裏需要注意一點：如果你修改了任一映射對象，記得需要先執行mvn clean再啓動項目，否則調試的時候會報錯。

結尾

MapStrut 的功能遠不至於上面介紹的這些，我只是挑出幾個常用的語法進行示例講解，如果讀者感興趣想深入的瞭解更多可以參考官方的參考文檔，Reference Guide。

遇見 MapStruct 後我就開始在項目中拋棄掉了原來的那些 BeanCopyUtils 的工具，相對而言 MapStruct 確實更簡潔且易使用而且定製功能也很強。

從編譯文件可以看出 MapStruct 是通過setter，getter來實現屬性值的拷貝，然後這種方式不是最簡單又最安全高效的嗎？只是 MapStruct 更好的幫助我們實現了，避免了項目中冗餘的重複代碼，大道至簡。