天天看點
傳回

基于AbstractProcessor擴充MapStruct自動生成實體映射工具類

作者：京東雲
作者：京東物流 王北永 姚再毅

1 背景

日常開發過程中，尤其在DDD過程中，經常遇到VO/MODEL/PO等領域模型的互相轉換。此時我們會一個字段一個字段進行set|get設定。要麼使用工具類進行暴力的屬性拷貝，在這個暴力屬性拷貝過程中好的工具更能提高程式的運作效率，反之引起性能低下、隐藏細節設定OOM等極端情況出現。

2 現有技術

  1. 直接set|get方法：字段少時還好，當字段非常大時工作量巨大，重複操作，費時費力。
  2. 通過反射+内省的方式實作值映射實作：比如許多開源的apache-common、spring、hutool工具類都提供了此種實作工具。這種方法的缺點就是性能低、黑盒屬性拷貝。不同工具類的處理又有差別：spring的屬性拷貝會忽略類型轉換但不報錯、hutool會自動進行類型轉、有些工具設定抛出異常等等。出現生産問題，定位比較困難。
  3. mapstruct：使用前需要手動定義轉換器接口,根據接口類注解和方法注解自動生成實作類，屬性轉換邏輯清晰，但是不同的領域對象轉換還需要單獨寫一層轉換接口或者添加一個轉換方法。

3 擴充設計

3.1 mapstruct介紹

本擴充元件基于mapstruct進行擴充，簡單介紹mapstruct實作原理。

mapstruct是基于JSR 269實作的，JSR 269是JDK引進的一種規範。有了它，能夠實作在編譯期處理注解，并且讀取、修改和添加抽象文法樹中的内容。JSR 269使用Annotation Processor在編譯期間處理注解，Annotation Processor相當于編譯器的一種插件，是以又稱為插入式注解處理。

我們知道，java的類加載機制是需要通過編譯期運作期。如下圖所示

基于AbstractProcessor擴充MapStruct自動生成實體映射工具類

mapstruct正是在上面的編譯期編譯源碼的過程中，通過修改文法樹二次生成位元組碼，如下圖所示

基于AbstractProcessor擴充MapStruct自動生成實體映射工具類

以上大概可以概括如下幾個步驟：

1、生成抽象文法樹。Java編譯器對Java源碼進行編譯，生成抽象文法樹（Abstract Syntax Tree，AST）。

2、調用實作了JSR 269 API的程式。隻要程式實作了JSR 269 API，就會在編譯期間調用實作的注解處理器。

3、修改抽象文法樹。在實作JSR 269 API的程式中，可以修改抽象文法樹，插入自己的實作邏輯。

4、生成位元組碼。修改完抽象文法樹後，Java編譯器會生成修改後的抽象文法樹對應的位元組碼檔案件。

從mapstruct實作原理來看，我們發現mapstruct屬性轉換邏輯清晰，具備良好的擴充性，問題是需要單獨寫一層轉換接口或者添加一個轉換方法。能否将轉換接口或者方法做到自動擴充呢？

3.2 改進方案

上面所說mapstruct方案，有個弊端。就是如果有新的領域模型轉換，我們不得不手動寫一層轉換接口，如果出現A/B兩個模型互轉，一般需定義四個方法：A->B、B->A、List<A>->List<B>、List<B>->List<A>

鑒于此，本方案通過将原mapstruct定義在轉換接口類注解和轉換方法的注解，通過映射，形成新包裝注解。将此注解直接定義在模型的類或者字段上，然後根據模型上的自定義注解直接編譯期生成轉換接口,然後mapstruct根據自動生成的接口再次生成具體的轉換實作類。

注意：自動生成的接口中類和方法的注解為原mapstruct的注解，是以mapstruct原有功能上沒有丢失。詳細調整如下圖：

基于AbstractProcessor擴充MapStruct自動生成實體映射工具類

4 實作

4.1 技術依賴

  1. 編譯期注解處理器AbstractProcessor：Annotation Processor相當于編譯器的一種插件，是以又稱為插入式注解處理。想要實作JSR 269，主要有以下幾個步驟。

1）繼承AbstractProcessor類，并且重寫process方法，在process方法中實作自己的注解處理邏輯。

2）在META-INF/services目錄下建立javax.annotation.processing.Processor檔案注冊自己實作的

2.谷歌AutoService：AutoService是Google開源的用來友善生成符合ServiceLoader規範的開源庫，使用非常的簡單。隻需要增加注解，便可自動生成規範限制檔案。

知識點：使用AutoService的好處是幫助我們不需要手動維護Annotation Processor所需要的META-INF檔案目錄和檔案内容。它會自動幫我們生産，使用方法也很簡單，隻需要在自定義的Annotation Processor類上加上以下注解即可 @AutoService(Processor.class)

  1. mapstruct：幫助實作自定義插件自動生成的轉換接口，并注入到spring容器中(現有方案中已做說明)。
  2. javapoet：JavaPoet是一個動态生成代碼的開源庫。幫助我們簡單快速的生成java類檔案，期主要特點如下：

1) JavaPoet是一款可以自動生成Java檔案的第三方依賴。

2) 簡潔易懂的API，上手快。

3) 讓繁雜、重複的Java檔案，自動化生成，提高工作效率，簡化流程。

4.2 實作步驟

  • 第一步：自動生成轉換接口類所需的枚舉，分别為類注解AlpacaMap和字段注解AlpacaMapField。

1） AlpacaMap：定義在類上，屬性target指定所轉換目标模型；屬性uses指定雷專轉換過程中所依賴的外部對象。

2）AlpacaMapField：原始mapstruct所支援的所有注解做一次别名包裝，使用spring提供的AliasFor注解。

知識點：@AliasFor是Spring架構的一個注解，用于聲明注解屬性的别名。它有兩種不同的應用場景：

注解内的别名

中繼資料的别名

兩者主要的差別在于是否在同一個注解内。

  • 第二步：AlpacaMapMapperDescriptor實作。此類主要功能是加載使用第一步定義枚舉的所有模型類，然後将類的資訊和類Field資訊儲存起來友善後面直接使用，片段邏輯如下： 
AutoMapFieldDescriptor descriptor = new AutoMapFieldDescriptor();
            descriptor.target = fillString(alpacaMapField.target());
            descriptor.dateFormat = fillString(alpacaMapField.dateFormat());
            descriptor.numberFormat = fillString(alpacaMapField.numberFormat());
            descriptor.constant = fillString(alpacaMapField.constant());
            descriptor.expression = fillString(alpacaMapField.expression());
            descriptor.defaultExpression = fillString(alpacaMapField.defaultExpression());
            descriptor.ignore = alpacaMapField.ignore();
             ..........
  • 第三步：AlpacaMapMapperGenerator類主要是通過JavaPoet生成對應的類資訊、類注解、類方法以及方法上的注解資訊 
生成類資訊：TypeSpec createTypeSpec(AlpacaMapMapperDescriptor descriptor)
生成類注解資訊 AnnotationSpec buildGeneratedMapperConfigAnnotationSpec(AlpacaMapMapperDescriptor descriptor) {
生成類方法資訊： MethodSpec buildMappingMethods(AlpacaMapMapperDescriptor descriptor)
生成方法注解資訊：List<AnnotationSpec> buildMethodMappingAnnotations(AlpacaMapMapperDescriptor descriptor){

在實作生成類資訊過程中，需要指定生成類的接口類AlpacaBaseAutoAssembler，此類主要定義四個方法如下：

public interface AlpacaBaseAutoAssembler<S,T>{
    T copy(S source);

    default List<T> copyL(List<S> sources){
        return sources.stream().map(c->copy(c)).collect(Collectors.toList());
    }

    @InheritInverseConfiguration(name = "copy")
    S reverseCopy(T source);

    default List<S> reverseCopyL(List<T> sources){
        return sources.stream().map(c->reverseCopy(c)).collect(Collectors.toList());
    }
}
  • 第四步：因為生成的類轉換器是注入spring容器的。是以需要頂一個專門生成mapstruct注入spring容器的注解，此注解通過類AlpacaMapSpringConfigGenerator自動生成，核心代碼如下 
private AnnotationSpec buildGeneratedMapperConfigAnnotationSpec() {
        return AnnotationSpec.builder(ClassName.get("org.mapstruct", "MapperConfig"))
                .addMember("componentModel", "$S", "spring")
                .build();
    }
  • 第五步：通過以上步驟，我們定義好了相關類、相關類的方法、相關類的注解、相關類方法的注解。此時将他們串起來通過Annotation Processor生成類檔案輸出，核心方法如下 
private void writeAutoMapperClassFile(AlpacaMapMapperDescriptor descriptor){
        System.out.println("開始生成接口："+descriptor.sourcePackageName() + "."+ descriptor.mapperName());
        try (final Writer outputWriter =
                     processingEnv
                             .getFiler()
                             .createSourceFile(  descriptor.sourcePackageName() + "."+ descriptor.mapperName())
                             .openWriter()) {
            alpacaMapMapperGenerator.write(descriptor, outputWriter);
        } catch (IOException e) {
            processingEnv
                    .getMessager()
                    .printMessage( ERROR,   "Error while opening "+ descriptor.mapperName()  + " output file: " + e.getMessage());
        }
    }

知識點：在javapoet中核心類第一大概有一下幾個類，可參考如下：

JavaFile 用于構造輸出包含一個頂級類的Java檔案, 是對.java檔案的抽象定義

TypeSpec TypeSpec是類/接口/枚舉的抽象類型

MethodSpec MethodSpec是方法/構造函數的抽象定義

FieldSpec FieldSpec是成員變量/字段的抽象定義

ParameterSpec ParameterSpec用于建立方法參數

AnnotationSpec AnnotationSpec用于建立标記注解

5 實踐

下面舉例說明如何使用，在這裡我們定義一個模型Person和模型Student，其中涉及字段轉換的普通字元串、枚舉、時間格式化和複雜的類型換磚，具體運用如下步驟。

5.1 引入依賴

代碼已上傳代碼庫，如需特定需求可重新拉去分支打包使用

<dependency>
            <groupId>com.jdl</groupId>
            <artifactId>alpaca-mapstruct-processor</artifactId>
            <version>1.1-SNAPSHOT</version>
        </dependency>

5.2 對象定義

uses方法必須為正常的spring容器中的bean，此bean提供@Named注解的方法可供類字段注解AlpacaMapField中的qualifiedByName 屬性以字元串的方式指定，如下圖所示

@Data
@AlpacaMap(targetType = Student.class,uses = {Person.class})
@Service
public class Person {
    private String make;
    private SexType type;

    @AlpacaMapField(target = "age")
    private Integer sax;

    @AlpacaMapField(target="dateStr" ,dateFormat = "yyyy-MM-dd")
    private Date date;

    @AlpacaMapField(target = "brandTypeName",qualifiedByName ="convertBrandTypeName")
    private Integer brandType;

    @Named("convertBrandTypeName")
    public  String convertBrandTypeName(Integer brandType){
        return BrandTypeEnum.getDescByValue(brandType);
    }

    @Named("convertBrandTypeName")
    public  Integer convertBrandType(String brandTypeName){
        return BrandTypeEnum.getValueByDesc(brandTypeName);
    }
}

5.3 生成結果

使用maven打包或者編譯後觀察，此時在target/generated-source/annotatins目錄中生成兩個檔案PersonToStudentAssembler和PersonToStudentAssemblerImpl

類檔案PersonToStudentAssembler 是由自定義注解器自動生成，内容如下

@Mapper(
    config = AutoMapSpringConfig.class,
    uses = {Person.class}
)
public interface PersonToStudentAssembler extends AlpacaBaseAutoAssembler<Person, Student> {
  @Override
  @Mapping(
      target = "age",
      source = "sax",
      ignore = false
  )
  @Mapping(
      target = "dateStr",
      dateFormat = "yyyy-MM-dd",
      source = "date",
      ignore = false
  )
  @Mapping(
      target = "brandTypeName",
      source = "brandType",
      ignore = false,
      qualifiedByName = "convertBrandTypeName"
  )
  Student copy(final Person source);
}

PersonToStudentAssemblerImpl是mapstruct根據PersonToStudentAssembler接口注解器自動生成，内容如下

@Component
public class PersonToStudentAssemblerImpl implements PersonToStudentAssembler {

    @Autowired
    private Person person;

    @Override
    public Person reverseCopy(Student arg0) {
        if ( arg0 == null ) {
            return null;
        }
        Person person = new Person();
        person.setSax( arg0.getAge() );
        try {
            if ( arg0.getDateStr() != null ) {
                person.setDate( new SimpleDateFormat( "yyyy-MM-dd" ).parse( arg0.getDateStr() ) );
            }
        } catch ( ParseException e ) {
            throw new RuntimeException( e );
        }
        person.setBrandType( person.convertBrandType( arg0.getBrandTypeName() ) );
        person.setMake( arg0.getMake() );
        person.setType( arg0.getType() );
        return person;
    }

    @Override
    public Student copy(Person source) {
        if ( source == null ) {
            return null;
        }
        Student student = new Student();
        student.setAge( source.getSax() );
        if ( source.getDate() != null ) {
            student.setDateStr( new SimpleDateFormat( "yyyy-MM-dd" ).format( source.getDate() ) );
        }
        student.setBrandTypeName( person.convertBrandTypeName( source.getBrandType() ) );
        student.setMake( source.getMake() );
        student.setType( source.getType() );
        return student;
    }
}

5.4 Spring容器引用

此時在我們的spring容器中可直接@Autowired引入接口PersonToStudentAssembler執行個體進行四種維護資料互相轉換

AnnotationConfigApplicationContext applicationContext = new  AnnotationConfigApplicationContext();
        applicationContext.scan("com.jdl.alpaca.mapstruct");
        applicationContext.refresh();
        PersonToStudentAssembler personToStudentAssembler = applicationContext.getBean(PersonToStudentAssembler.class);
        Person person = new Person();
        person.setMake("make");
        person.setType(SexType.BOY);
        person.setSax(100);
        person.setDate(new Date());
        person.setBrandType(1);
        Student student = personToStudentAssembler.copy(person);
        System.out.println(student);
        System.out.println(personToStudentAssembler.reverseCopy(student));
        List<Person> personList = Lists.newArrayList();
        personList.add(person);
        System.out.println(personToStudentAssembler.copyL(personList));
        System.out.println(personToStudentAssembler.reverseCopyL(personToStudentAssembler.copyL(personList)));

控制台列印：

personToStudentStudent(make=make, type=BOY, age=100, dateStr=2022-11-09, brandTypeName=集團KA)
studentToPersonPerson(make=make, type=BOY, sax=100, date=Wed Nov 09 00:00:00 CST 2022, brandType=1)
personListToStudentList[Student(make=make, type=BOY, age=100, dateStr=2022-11-09, brandTypeName=集團KA)]
studentListToPersonList[Person(make=make, type=BOY, sax=100, date=Wed Nov 09 00:00:00 CST 2022, brandType=1)]

注意：

  • qualifiedByName注解屬性使用不太友好，如果使用到此屬性時，需要定義反轉類型轉換函數。因為在前面我們定義的抽象接口AlpacaBaseAutoAssembler有如下圖一個注解，從目的對象到源對象的反轉映射，因為java的重載性，同名不同參非同一個方法，是以在S轉T的時候回找不到此方法。故需要自行定義好轉換函數 
@InheritInverseConfiguration(name = "copy")

比如從S轉換T會使用第一個方法，從T轉S的時候必須定義一個同名Named注解的方法，方法參數和前面方法是入參變出參、出參變入參。

@Named("convertBrandTypeName")
    public  String convertBrandTypeName(Integer brandType){
        return BrandTypeEnum.getDescByValue(brandType);
    }

    @Named("convertBrandTypeName")
    public  Integer convertBrandType(String brandTypeName){
        return BrandTypeEnum.getValueByDesc(brandTypeName);
    }
  • 在使用qualifiedByName注解時，指定的Named注解方法必須定義為spring容器可管理的對象，并需要通過模型類注解屬性used引入此對象Class

知識點：

InheritInverseConfiguration功能很強大，可以逆向映射，從上面PersonToStudentAssemblerImpl看到上面屬性sax可以正映射到sex，逆映射可自動從sex映射到sax。但是正映射的@Mapping#expression、#defaultExpression、#defaultValue和#constant會被逆映射忽略。此外某個字段的逆映射可以被ignore，expression或constant覆寫

6 結束語

參考文檔：

https://github.com/google/auto/tree/master/service

https://mapstruct.org/

https://github.com/square/javapoet

映射工具 實體映射 自動生成 mapstruct trac roce
上一篇: 可以用很久的女生頭像
下一篇: JS小知識，分享20個有用 JavaScript 小技巧上篇（六）

繼續閱讀