基于AbstractProcessor扩展MapStruct自动生成实体映射工具类

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

1 背景

日常开发过程中，尤其在 DDD 过程中，经常遇到 VO/MODEL/PO 等领域模型的相互转换。此时我们会一个字段一个字段进行 set|get 设置。要么使用工具类进行暴力的属性拷贝，在这个暴力属性拷贝过程中好的工具更能提高程序的运行效率，反之引起性能低下、隐藏细节设置 OOM 等极端情况出现。

2 现有技术

1. 直接 set|get 方法：字段少时还好，当字段非常大时工作量巨大，重复操作，费时费力。

1. 通过反射 + 内省的方式实现值映射实现：比如许多开源的 apache-common、spring、hutool 工具类都提供了此种实现工具。这种方法的缺点就是性能低、黑盒属性拷贝。不同工具类的处理又有区别：spring 的属性拷贝会忽略类型转换但不报错、hutool 会自动进行类型转、有些工具设置抛出异常等等。出现生产问题，定位比较困难。

1. mapstruct：使用前需要手动定义转换器接口，根据接口类注解和方法注解自动生成实现类，属性转换逻辑清晰，但是不同的领域对象转换还需要单独写一层转换接口或者添加一个转换方法。

3 扩展设计

3.1 mapstruct 介绍

本扩展组件基于 mapstruct 进行扩展，简单介绍 mapstruct 实现原理。

mapstruct 是基于 JSR 269 实现的，JSR 269 是 JDK 引进的一种规范。有了它，能够实现在编译期处理注解，并且读取、修改和添加抽象语法树中的内容。JSR 269 使用 Annotation Processor 在编译期间处理注解，Annotation Processor 相当于编译器的一种插件，因此又称为插入式注解处理。

我们知道，java 的类加载机制是需要通过编译期运行期。如下图所示

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 两个模型互转，一般需定义四个方法：

鉴于此，本方案通过将原 mapstruct 定义在转换接口类注解和转换方法的注解，通过映射，形成新包装注解。将此注解直接定义在模型的类或者字段上，然后根据模型上的自定义注解直接编译期生成转换接口，然后 mapstruct 根据自动生成的接口再次生成具体的转换实现类。

注意：自动生成的接口中类和方法的注解为原 mapstruct 的注解，所以 mapstruct 原有功能上没有丢失。详细调整如下图：

4 实现

4.1 技术依赖

1. 编译期注解处理器 AbstractProcessor：Annotation Processor 相当于编译器的一种插件，因此又称为插入式注解处理。想要实现 JSR 269，主要有以下几个步骤。

1）继承 AbstractProcessor 类，并且重写 process 方法，在 process 方法中实现自己的注解处理逻辑。

2）在 META-INF/services 目录下创建 javax.annotation.processing.Processor 文件注册自己实现的

1. 谷歌 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