Article directory
1. Introduction:
MapStruct is a Java annotation processor used to automatically generate mapping code between Java beans.
It can greatly simplify the process of data conversion and reduce the workload of manually writing conversion code.
2. Background:
In actual development, we often encounter situations where we need to convert data from one Java bean to another Java bean.
In the absence of automatic conversion tools, we usually need to manually write conversion code to assign the attribute values of the source object to the corresponding attributes of the target object one by one.
Such conversion code is often very verbose and error-prone.
To solve this problem, MapStruct came into being.
It adds annotations to Java bean classes, specifies the mapping relationship between source objects and target objects, and then uses an annotation processor to automatically generate conversion code.
In this way, developers no longer need to manually write conversion codes, greatly improving development efficiency and code quality.
3. Related concepts:
1. Mapper:
A mapper is an interface that defines conversion rules between source and target objects. We can define multiple abstract methods in the mapper interface, each method represents a specific transformation rule. The @Mapper annotation needs to be added to the mapper interface to tell MapStruct to generate conversion code for the interface.
2. Mapping Method:
The mapping method is an abstract method in the mapper interface, which is used to define the attribute mapping relationship between the source object and the target object. The @Mapping annotation needs to be added to the mapping method to specify the mapping relationship between source attributes and target attributes.
3. Regular Mapping Method:
The conventional mapping method is used to assign the attribute values of the source object to the corresponding attributes of the target object one by one. This is the most common mapping method, and its parameter list needs to contain the source object and the target object.
4. Nested Mapping Method:
The nested mapping method is used to handle the nested relationship between the source object and the target object. When there are nested objects in the source and target objects, we can use the nested mapping method to handle the conversion between nested objects.
5. Collection Mapping Method:
The collection mapping method is used to handle the collection relationship between source objects and target objects. When collection properties exist in the source and target objects, we can use the collection mapping method to handle the conversion between collection properties.
In short, MapStruct is a convenient and powerful Java conversion tool that can help developers automatically generate mapping codes between Java beans and reduce the workload of manually writing conversion codes. Its use is very simple, just add annotations and define conversion rules.
4. Use cases
The following gives an example of different properties of the source object and the target object to illustrate how to use MapStruct for conversion.
Suppose we have the following two classes:
public class SourceObject {
private String name;
private int age;
// getters and setters
}
public class TargetObject {
private String fullName;
private int yearsOld;
// getters and setters
}
The name attribute of the source object corresponds to the fullName attribute of the target object, and the age attribute of the source object corresponds to the yearsOld attribute of the target object.
Then we need to perform the following steps:
1. Add dependencies:
Add MapStruct dependency in the project's pom.xml file.
<dependency>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct</artifactId>
<version>1.4.2.Final</version>
</dependency>
2. Create a converter interface:
Define an interface, mark it with the @Mapper annotation, and specify the componentModel parameter as spring (if using the Spring framework).
@Mapper(componentModel = "spring")
public interface ObjectMapper {
@Mapping(source = "name", target = "fullName")
@Mapping(source = "age", target = "yearsOld")
TargetObject sourceToTarget(SourceObject sourceObject);
}
In this example, we use the @Mapping annotation to specify the mapping relationship between source properties and target properties.
3. Generate converter implementation class:
Use Maven to build the project, and MapStruct will automatically generate an implementation class that implements the converter interface.
4. Use a converter:
Use converters for object conversion in code.
SourceObject source = new SourceObject();
source.setName("John");
source.setAge(25);
ObjectMapper mapper = new ObjectMapperImpl(); // 自动生成的实现类
TargetObject target = mapper.sourceToTarget(source);
System.out.println(target.getFullName()); // 输出 "John"
System.out.println(target.getYearsOld()); // 输出 25
Now, you can see that the name property of the source object is mapped to the fullName property of the target object, and the age property of the source object is mapped to the yearsOld property of the target object. In this way, you can use MapStruct to perform mapping conversions with different attributes of the source object and target object.
5. The underlying principles of MapStruct
The underlying principle of MapStruct is to use the Java annotation processor (Annotation Processor) to generate conversion code. The annotation processor is a tool that scans and processes annotations at compile time. It can read the annotation information in the source code and generate new Java code based on the annotation information.
When we add the @Mapper annotation on the mapper interface, the annotation processor scans the annotation information on the interface and its methods and generates conversion code based on the annotation information. The specific process is as follows:
1. Scan mapper interface:
The annotation processor scans the annotation information on the mapper interface to obtain metadata such as source and target object types, mapping methods, etc.
2. Analytical mapping method:
The annotation processor will parse the annotation information on the mapping method, including the mapping relationship between source attributes and target attributes, conversion logic, etc.
3. Generate conversion code:
According to the types of the source object and target object and the annotation information of the mapping method, the annotation processor will generate conversion code and assign the attribute values of the source object to the corresponding attributes of the target object.
4. Compiler processing:
The generated conversion code will be written to the output stream of the compiler by the annotation processor, and the compiler will compile the code into a bytecode file.
5. Use conversion code:
At actual runtime, we can directly use the generated conversion code and call the mapping method to convert between objects.
By using an annotation processor, MapStruct can automatically generate conversion code at compile time, avoiding runtime performance overhead and improving conversion efficiency. At the same time, because the code is generated at compile time, the generated conversion code can be verified and debugged during the development phase, reducing the possibility of errors in writing manual conversion code.