基於AbstractProcessor擴充套件MapStruct自動生成實體對映工具類
作者：京東物流 王北永 姚再毅
1 背景
日常開發過程中，尤其在 DDD 過程中，經常遇到 VO/MODEL/PO 等領域模型的相互轉換。此時我們會一個欄位一個欄位進行 set|get 設定。要麼使用工具類進行暴力的屬性拷貝，在這個暴力屬性拷貝過程中好的工具更能提高程式的執行效率，反之引起效能低下、隱藏細節設定 OOM 等極端情況出現。
2 現有技術
- 直接 set|get 方法：欄位少時還好，當欄位非常大時工作量巨大，重複操作，費時費力。
- 通過反射 + 內省的方式實現值對映實現：比如許多開源的 apache-common、spring、hutool 工具類都提供了此種實現工具。這種方法的缺點就是效能低、黑盒屬性拷貝。不同工具類的處理又有區別：spring 的屬性拷貝會忽略型別轉換但不報錯、hutool 會自動進行型別轉、有些工具設定丟擲異常等等。出現生產問題，定位比較困難。
- 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 技術依賴
- 編譯期註解處理器 AbstractProcessor：Annotation Processor 相當於編譯器的一種外掛，因此又稱為插入式註解處理。想要實現 JSR 269，主要有以下幾個步驟。
1）繼承 AbstractProcessor 類，並且重寫 process 方法，在 process 方法中實現自己的註解處理邏輯。
2）在 META-INF/services 目錄下建立 javax.annotation.processing.Processor 檔案註冊自己實現的
- 谷歌 AutoService：AutoService 是 Google 開源的用來方便生成符合 ServiceLoader 規範的開源庫，使用非常的簡單。只需要增加註解，便可自動生成規範約束檔案。
知識點： 使用 AutoService 的好處是幫助我們不需要手動維護 Annotation Processor 所需要的 META-INF 檔案目錄和檔案內容。它會自動幫我們生產，使用方法也很簡單，只需要在自定義的 Annotation Processor 類上加上以下註解即可 @AutoService (Processor.class)
- mapstruct：幫助實現自定義外掛自動生成的轉換介面，並注入到 spring 容器中 (現有方案中已做說明)。
- javapoet：JavaPoet 是一個動態生成程式碼的開源庫。幫助我們簡單快速的生成 java 類檔案，期主要特點如下：
-
JavaPoet 是一款可以自動生成 Java 檔案的第三方依賴。
-
簡潔易懂的 API，上手快。
-
讓繁雜、重複的 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://github.com/square/javapoet