AbstractProcessor擴(kuò)展MapStruct自動(dòng)生成實(shí)體映射工具類

更新時(shí)間：2023年01月28日 15:29:13 作者：京東云開發(fā)者

這篇文章主要為大家介紹了AbstractProcessor擴(kuò)展MapStruct自動(dòng)生成實(shí)體映射工具類實(shí)現(xiàn)詳解，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進(jìn)步，早日升職加薪

1 背景

日常開發(fā)過程中，尤其在 DDD 過程中，經(jīng)常遇到 VO/MODEL/PO 等領(lǐng)域模型的相互轉(zhuǎn)換。此時(shí)我們會(huì)一個(gè)字段一個(gè)字段進(jìn)行 set|get 設(shè)置。要么使用工具類進(jìn)行暴力的屬性拷貝，在這個(gè)暴力屬性拷貝過程中好的工具更能提高程序的運(yùn)行效率，反之引起性能低下、隱藏細(xì)節(jié)設(shè)置 OOM 等極端情況出現(xiàn)。

2 現(xiàn)有技術(shù)

直接 set|get 方法：字段少時(shí)還好，當(dāng)字段非常大時(shí)工作量巨大，重復(fù)操作，費(fèi)時(shí)費(fèi)力。
通過反射 + 內(nèi)省的方式實(shí)現(xiàn)值映射實(shí)現(xiàn)：比如許多開源的 apache-common、spring、hutool 工具類都提供了此種實(shí)現(xiàn)工具。這種方法的缺點(diǎn)就是性能低、黑盒屬性拷貝。不同工具類的處理又有區(qū)別：spring 的屬性拷貝會(huì)忽略類型轉(zhuǎn)換但不報(bào)錯(cuò)、hutool 會(huì)自動(dòng)進(jìn)行類型轉(zhuǎn)、有些工具設(shè)置拋出異常等等。出現(xiàn)生產(chǎn)問題，定位比較困難。
mapstruct：使用前需要手動(dòng)定義轉(zhuǎn)換器接口，根據(jù)接口類注解和方法注解自動(dòng)生成實(shí)現(xiàn)類，屬性轉(zhuǎn)換邏輯清晰，但是不同的領(lǐng)域?qū)ο筠D(zhuǎn)換還需要單獨(dú)寫一層轉(zhuǎn)換接口或者添加一個(gè)轉(zhuǎn)換方法。

3 擴(kuò)展設(shè)計(jì)

3.1 mapstruct 介紹

本擴(kuò)展組件基于 mapstruct 進(jìn)行擴(kuò)展，簡(jiǎn)單介紹 mapstruct 實(shí)現(xiàn)原理。

mapstruct 是基于 JSR 269 實(shí)現(xiàn)的，JSR 269 是 JDK 引進(jìn)的一種規(guī)范。有了它，能夠?qū)崿F(xiàn)在編譯期處理注解，并且讀取、修改和添加抽象語法樹中的內(nèi)容。JSR 269 使用 Annotation Processor 在編譯期間處理注解，Annotation Processor 相當(dāng)于編譯器的一種插件，因此又稱為插入式注解處理。

我們知道，java 的類加載機(jī)制是需要通過編譯期運(yùn)行期。如下圖所示

mapstruct 正是在上面的編譯期編譯源碼的過程中，通過修改語法樹二次生成字節(jié)碼，如下圖所示

以上大概可以概括如下幾個(gè)步驟：

1、生成抽象語法樹。Java 編譯器對(duì) Java 源碼進(jìn)行編譯，生成抽象語法樹（Abstract Syntax Tree，AST）。

2、調(diào)用實(shí)現(xiàn)了 JSR 269 API 的程序。只要程序?qū)崿F(xiàn)了 JSR 269 API，就會(huì)在編譯期間調(diào)用實(shí)現(xiàn)的注解處理器。

3、修改抽象語法樹。在實(shí)現(xiàn) JSR 269 API 的程序中，可以修改抽象語法樹，插入自己的實(shí)現(xiàn)邏輯。

4、生成字節(jié)碼。修改完抽象語法樹后，Java 編譯器會(huì)生成修改后的抽象語法樹對(duì)應(yīng)的字節(jié)碼文件件。

從 mapstruct 實(shí)現(xiàn)原理來看，我們發(fā)現(xiàn) mapstruct 屬性轉(zhuǎn)換邏輯清晰，具備良好的擴(kuò)展性，問題是需要單獨(dú)寫一層轉(zhuǎn)換接口或者添加一個(gè)轉(zhuǎn)換方法。能否將轉(zhuǎn)換接口或者方法做到自動(dòng)擴(kuò)展呢？

3.2 改進(jìn)方案

上面所說 mapstruct 方案，有個(gè)弊端。就是如果有新的領(lǐng)域模型轉(zhuǎn)換，我們不得不手動(dòng)寫一層轉(zhuǎn)換接口，如果出現(xiàn) A/B 兩個(gè)模型互轉(zhuǎn)，一般需定義四個(gè)方法：

鑒于此，本方案通過將原 mapstruct 定義在轉(zhuǎn)換接口類注解和轉(zhuǎn)換方法的注解，通過映射，形成新包裝注解。將此注解直接定義在模型的類或者字段上，然后根據(jù)模型上的自定義注解直接編譯期生成轉(zhuǎn)換接口，然后 mapstruct 根據(jù)自動(dòng)生成的接口再次生成具體的轉(zhuǎn)換實(shí)現(xiàn)類。

注意：自動(dòng)生成的接口中類和方法的注解為原 mapstruct 的注解，所以 mapstruct 原有功能上沒有丟失。詳細(xì)調(diào)整如下圖：

4 實(shí)現(xiàn)

4.1 技術(shù)依賴

編譯期注解處理器 AbstractProcessor：Annotation Processor 相當(dāng)于編譯器的一種插件，因此又稱為插入式注解處理。想要實(shí)現(xiàn) JSR 269，主要有以下幾個(gè)步驟。

1）繼承 AbstractProcessor 類，并且重寫 process 方法，在 process 方法中實(shí)現(xiàn)自己的注解處理邏輯。

2）在 META-INF/services 目錄下創(chuàng)建 javax.annotation.processing.Processor 文件注冊(cè)自己實(shí)現(xiàn)的

谷歌 AutoService：AutoService 是 Google 開源的用來方便生成符合 ServiceLoader 規(guī)范的開源庫(kù)，使用非常的簡(jiǎn)單。只需要增加注解，便可自動(dòng)生成規(guī)范約束文件。

知識(shí)點(diǎn)： 使用 AutoService 的好處是幫助我們不需要手動(dòng)維護(hù) Annotation Processor 所需要的 META-INF 文件目錄和文件內(nèi)容。它會(huì)自動(dòng)幫我們生產(chǎn)，使用方法也很簡(jiǎn)單，只需要在自定義的 Annotation Processor 類上加上以下的注解即可 @AutoService (Processor.class)

mapstruct：幫助實(shí)現(xiàn)自定義插件自動(dòng)生成的轉(zhuǎn)換接口，并注入到 spring 容器中 (現(xiàn)有方案中已做說明)。
javapoet：JavaPoet 是一個(gè)動(dòng)態(tài)生成代碼的開源庫(kù)。幫助我們簡(jiǎn)單快速的生成 java 類文件，期主要特點(diǎn)如下：

JavaPoet 是一款可以自動(dòng)生成 Java 文件的第三方依賴。

簡(jiǎn)潔易懂的 API，上手快。

讓繁雜、重復(fù)的 Java 文件，自動(dòng)化生成，提高工作效率，簡(jiǎn)化流程。

4.2 實(shí)現(xiàn)步驟

第一步：自動(dòng)生成轉(zhuǎn)換接口類所需的枚舉，分別為類注解 AlpacaMap 和字段注解 AlpacaMapField。

1） AlpacaMap：定義在類上，屬性 target 指定所轉(zhuǎn)換目標(biāo)模型；屬性 uses 指定雷專轉(zhuǎn)換過程中所依賴的外部對(duì)象。

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

知識(shí)點(diǎn)： @AliasFor 是 Spring 框架的一個(gè)注解，用于聲明注解屬性的別名。它有兩種不同的應(yīng)用場(chǎng)景：

注解內(nèi)的別名

元數(shù)據(jù)的別名

兩者主要的區(qū)別在于是否在同一個(gè)注解內(nèi)。

第二步：AlpacaMapMapperDescriptor 實(shí)現(xiàn)。此類主要功能是加載使用第一步定義枚舉的所有模型類，然后將類的信息和類 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 生成對(duì)應(yīng)的類信息、類注解、類方法以及方法上的注解信息

生成類信息：TypeSpec createTypeSpec(AlpacaMapMapperDescriptor descriptor)

生成類注解信息 AnnotationSpec buildGeneratedMapperConfigAnnotationSpec(AlpacaMapMapperDescriptor descriptor) {

生成類方法信息： MethodSpec buildMappingMethods(AlpacaMapMapperDescriptor descriptor)

生成方法注解信息：List<AnnotationSpec> buildMethodMappingAnnotations(AlpacaMapMapperDescriptor descriptor){

在實(shí)現(xiàn)生成類信息過程中，需要指定生成類的接口類 AlpacaBaseAutoAssembler，此類主要定義四個(gè)方法如下：

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());
    }
}

第四步：因?yàn)樯傻念愞D(zhuǎn)換器是注入 spring 容器的。所以需要頂一個(gè)專門生成 mapstruct 注入 spring 容器的注解，此注解通過類 AlpacaMapSpringConfigGenerator 自動(dòng)生成，核心代碼如下

private AnnotationSpec buildGeneratedMapperConfigAnnotationSpec() {
        return AnnotationSpec.builder(ClassName.get("org.mapstruct", "MapperConfig"))
                .addMember("componentModel", "$S", "spring")
                .build();
    }

第五步：通過以上步驟，我們定義好了相關(guān)類、相關(guān)類的方法、相關(guān)類的注解、相關(guān)類方法的注解。此時(shí)將他們串起來通過 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());
        }
    }

知識(shí)點(diǎn)： 在 javapoet 中核心類第一大概有一下幾個(gè)類，可參考如下：

JavaFile 用于構(gòu)造輸出包含一個(gè)頂級(jí)類的 Java 文件，是對(duì).java 文件的抽象定義

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

MethodSpec MethodSpec 是方法 / 構(gòu)造函數(shù)的抽象定義

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

ParameterSpec ParameterSpec 用于創(chuàng)建方法參數(shù)

AnnotationSpec AnnotationSpec 用于創(chuàng)建標(biāo)記注解

5 實(shí)踐

下面舉例說明如何使用，在這里我們定義一個(gè)模型 Person 和模型 Student，其中涉及字段轉(zhuǎn)換的普通字符串、枚舉、時(shí)間格式化和復(fù)雜的類型換磚，具體運(yùn)用如下步驟。

5.1 引入依賴

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

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

5.2 對(duì)象定義

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 生成結(jié)果

使用 maven 打包或者編譯后觀察，此時(shí)在 target/generated-source/annotatins 目錄中生成兩個(gè)文件 PersonToStudentAssembler 和 PersonToStudentAssemblerImpl

類文件 PersonToStudentAssembler 是由自定義注解器自動(dòng)生成，內(nèi)容如下

@Mapper(
    config = AutoMapSpringConfig.class,
    uses = {Person.class}
)
public interface PersonToStudentAssembler extends AlpacaBaseAutoAssembler&lt;Person, Student&gt; {
  @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 根據(jù) PersonToStudentAssembler 接口注解器自動(dòng)生成，內(nèi)容如下

@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 容器引用

此時(shí)在我們的 spring 容器中可直接 @Autowired 引入接口 PersonToStudentAssembler 實(shí)例進(jìn)行四種維護(hù)數(shù)據(jù)相互轉(zhuǎn)換

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)));

控制臺(tái)打?。?/p>

personToStudentStudent(make=make, type=BOY, age=100, dateStr=2022-11-09, brandTypeName=集團(tuán)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=集團(tuán)KA)]
studentListToPersonList[Person(make=make, type=BOY, sax=100, date=Wed Nov 09 00:00:00 CST 2022, brandType=1)]

注意：

qualifiedByName 注解屬性使用不太友好，如果使用到此屬性時(shí)，需要定義反轉(zhuǎn)類型轉(zhuǎn)換函數(shù)。因?yàn)樵谇懊嫖覀兌x的抽象接口 AlpacaBaseAutoAssembler 有如下圖一個(gè)注解，從目的對(duì)象到源對(duì)象的反轉(zhuǎn)映射，因?yàn)?java 的重載性，同名不同參非同一個(gè)方法，所以在 S 轉(zhuǎn) T 的時(shí)候回找不到此方法。故需要自行定義好轉(zhuǎn)換函數(shù)

@InheritInverseConfiguration(name = "copy")

比如從 S 轉(zhuǎn)換 T 會(huì)使用第一個(gè)方法，從 T 轉(zhuǎn) S 的時(shí)候必須定義一個(gè)同名 Named 注解的方法，方法參數(shù)和前面方法是入?yún)⒆兂鰠?、出參變?nèi)雲(yún)ⅰ?/p>

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

在使用 qualifiedByName 注解時(shí)，指定的 Named 注解方法必須定義為 spring 容器可管理的對(duì)象，并需要通過模型類注解屬性 used 引入此對(duì)象 Class

知識(shí)點(diǎn)：

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