MapStructPlus

https://www.mapstruct.plus/guide/
Admin
MapStructPlus is an enhanced MapStruct tool that automatically generates Mapper interfaces and...
Tokens:6,190
Snippets:72
Trust Score:4.4
Update:6 months ago
Show doc for...
Tokens:
Raw
### Define Circular Reference Classes

Source: https://www.mapstruct.plus/guide/cycle-avoiding.html

Example of source and target classes containing bidirectional references that cause stack overflow during mapping.

```java
@Data
public class TreeNode {
    private TreeNode parent;
    private List<TreeNode> children;
}

@Data
public class TreeNodeDto {
    private TreeNodeDto parent;
    private List<TreeNodeDto> children;
}
```

--------------------------------

### Lombok 1.18.16 之前版本整合配置

Source: https://www.mapstruct.plus/guide/faq.html

适用于 Lombok 1.18.16 之前的 Maven 和 Gradle 配置，需在 annotationProcessorPaths 中添加 lombok 和 mapstruct-plus-processor。

```xml
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>${lombok.version}</version>
                    </path>
                    <path>
                        <groupId>io.github.linpeilie</groupId>
                        <artifactId>mapstruct-plus-processor</artifactId>
                        <version>${mapstruct-plus.version}</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>
```

```gradle
dependencies {
    annotationProcessor group: 'org.projectlombok', name: 'lombok', version: {lombok.version}
    annotationProcessor group: 'io.github.linpeilie', name: 'mapstruct-plus-processor', version: ${mapstruct-plus.version}
}
```

--------------------------------

### MapStruct Plus Configuration Parameters

Source: https://www.mapstruct.plus/guide/configuration.html

Overview of available configuration parameters for MapStruct Plus mapping behavior.

```APIDOC
## MapStruct Plus Configuration Parameters

### typeConversionPolicy
- **Description**: Strategy for handling lossy conversions (e.g., long to int).
- **Type**: ReportingPolicy
- **Options**: IGNORE, WARN, ERROR
- **Default**: IGNORE
- **Compiler Argument**: -Amapstruct.plus.typeConversionPolicy

### collectionMappingStrategy
- **Description**: Strategy for mapping collection properties.
- **Type**: CollectionMappingStrategy
- **Options**: ACCESSOR_ONLY, SETTER_PREFERRED, ADDER_PREFERRED, TARGET_IMMUTABLE
- **Default**: ACCESSOR_ONLY
- **Compiler Argument**: -Amapstruct.plus.collectionMappingStrategy

### nullValueIterableMappingStrategy
- **Description**: Strategy applied when null is passed as a source parameter to IterableMapping.
- **Type**: NullValueMappingStrategy
- **Options**: RETURN_NULL, RETURN_DEFAULT
- **Default**: RETURN_NULL
- **Compiler Argument**: -Amapstruct.plus.nullValueIterableMappingStrategy

### nullValueMapMappingStrategy
- **Description**: Strategy applied when null is passed as a source parameter to MapMapping.
- **Type**: NullValueMappingStrategy
- **Options**: RETURN_NULL, RETURN_DEFAULT
- **Default**: RETURN_NULL
- **Compiler Argument**: -Amapstruct.plus.nullValueMapMappingStrategy

### nullValueCheckStrategy
- **Description**: Determines when to perform null checks on source property values.
- **Type**: NullValueCheckStrategy
- **Options**: ON_IMPLICIT_CONVERSION, ALWAYS
- **Default**: ON_IMPLICIT_CONVERSION
- **Compiler Argument**: -Amapstruct.plus.nullValueCheckStrategy

### mappingControl
- **Description**: Allows detailed control over the mapping process.
- **Type**: Class
- **Default**: MappingControl.class

### unexpectedValueMappingException
- **Description**: Exception thrown if an enum has no matching mapping.
- **Type**: Class
- **Default**: IllegalArgumentException.class

### suppressTimestampInGenerated
- **Description**: Whether to suppress the timestamp in the @Generated annotation.
- **Type**: boolean
- **Default**: false
- **Compiler Argument**: -Amapstruct.plus.suppressTimestampInGenerated
```

--------------------------------

### Convert Object to New Instance

Source: https://www.mapstruct.plus/guide/converter-api.html

Use this method to convert a source object to a new instance of the target type. Provide the source object and the target class.

```java
T convert(S source, Class<T> targetType)
```

--------------------------------

### Test Enum Conversion

Source: https://www.mapstruct.plus/guide/enum-convert.html

A test case demonstrating the conversion between the source object and the DTO, verifying the enum mapping.

```java
@Test
public void enumMapTest() {
    final GoodsVo goodsVo = converter.convert(goods, GoodsVo.class);
    System.out.println(goodsVo);
    Assert.equals(goodsVo.getState(), goods.getState().getState());

    final Goods goods2 = converter.convert(goodsVo, Goods.class);
    System.out.println(goods2);
    Assert.equals(goods2.getState(), GoodsStateEnum.ENABLED);
}
```

--------------------------------

### Lombok 1.18.16 及以后版本整合配置

Source: https://www.mapstruct.plus/guide/faq.html

适用于 Lombok 1.18.16 及以后的版本，必须额外引入 lombok-mapstruct-binding 以确保兼容性。

```xml
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>${lombok.version}</version>
                    </path>
                    <path>
                        <groupId>io.github.linpeilie</groupId>
                        <artifactId>mapstruct-plus-processor</artifactId>
                        <version>${mapstruct-plus.version}</version>
                    </path>
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok-mapstruct-binding</artifactId>
                        <version>0.2.0</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>
```

```gradle
dependencies {
    annotationProcessor group: 'org.projectlombok', name: 'lombok', version: {lombok.version}
    annotationProcessor group: 'io.github.linpeilie', name: 'mapstruct-plus-processor', version: ${mapstruct-plus.version}
    annotationProcessor group: 'org.projectlombok', name: 'lombok-mapstruct-binding', version: '0.2.0'
}
```

--------------------------------

### Configure Specific Mapping Rules for Different Target Classes

Source: https://www.mapstruct.plus/guide/multiple-class-convert.html

When mapping to multiple classes, use `@AutoMappings` and `@AutoMapping` with the `targetClass` attribute to define specific rules for each target. If `targetClass` is omitted, the rule applies to all conversions. The `targetClass` also supports parent classes.

```java
@Data
@AutoMappers({
    @AutoMapper(target = UserDto.class),
    @AutoMapper(target = UserVO.class)
})
public class User {

    private String username;

    private int age;
    private boolean young;

    @AutoMapping(targetClass = UserDto.class, target = "educations", expression = "java(java.lang.String.join(\",\", source.getEducationList()))")
    private List<String> educationList;

    @AutoMappings({
        @AutoMapping(targetClass = UserDto.class, dateFormat = "yyyy-MM-dd HH:mm:ss"),
        @AutoMapping(targetClass = UserVO.class, ignore = true)
    })
    private Date birthday;

    @AutoMapping(targetClass = UserDto.class, numberFormat = "$0.00")
    private double assets;

    @AutoMapping(numberFormat = "$0.00")
    private double money;

    @AutoMappings({
        @AutoMapping(targetClass = UserVO.class, target = "voField")
    })
    private String voField;

}
```

--------------------------------

### Convert Object to Existing Instance

Source: https://www.mapstruct.plus/guide/converter-api.html

Use this method to convert a source object's properties into an existing target object. This modifies the provided target object.

```java
T convert(S source, T target)
```

--------------------------------

### Add MapStruct Plus Spring Boot Starter Dependency (Maven)

Source: https://www.mapstruct.plus

Include this dependency in your Maven project to integrate MapStruct Plus with Spring Boot.

```xml
<dependency>
    <groupId>io.github.linpeilie</groupId>
    <artifactId>mapstruct-plus-spring-boot-starter</artifactId>
    <version>1.5.0</version>
</dependency>
```

--------------------------------

### Convert Map to Object

Source: https://www.mapstruct.plus/guide/converter-api.html

Use this method to convert a Map<String, Object> into an instance of the specified target class. Ensure the map keys correspond to the target class's properties.

```java
T convert(Map<String, Object> map, Class<T> target)
```

--------------------------------

### Add MapStruct Plus Spring Boot Starter Dependency (Gradle)

Source: https://www.mapstruct.plus

Include this dependency in your Gradle project to integrate MapStruct Plus with Spring Boot.

```gradle
implementation group: 'io.github.linpeilie', name: 'mapstruct-plus-spring-boot-starter', version: '1.5.0'
```

--------------------------------

### Convert List of Objects

Source: https://www.mapstruct.plus/guide/converter-api.html

This method converts a collection of source objects into a collection of target objects. Specify the source list and the target class.

```java
List<T> convert(List<S> source, Class<T> targetType)
```

--------------------------------

### Define Property Dependencies

Source: https://www.mapstruct.plus/guide/class-convert.html

Use dependsOn to ensure specific fields are processed before others during the mapping sequence.

```java
@Data
@AutoMapper(target = DependsTarget.class)
public class DependsSource {

    private String firstName;
    private String lastName;
    @AutoMapping(dependsOn = {"firstName", "lastName"})
    private String fullName;

}
```

```java
@Data
public class DependsTarget {

    private String firstName;
    private String lastName;
    private String fullName;

}
```

--------------------------------

### Add Hutool Dependency

Source: https://www.mapstruct.plus/guide/map-to-class.html

Required for MapStructPlus 1.4.0 and later versions to enable type conversion features.

```xml
<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-core</artifactId>
    <version>${hutool.version}</version>
</dependency>
```

--------------------------------

### Configure AutoMapper with cycleAvoiding

Source: https://www.mapstruct.plus/guide/cycle-avoiding.html

Enable cycleAvoiding in the @AutoMapper annotation to handle circular references safely.

```java
@Data
@AutoMapper(target = TreeNodeDto.class, cycleAvoiding = true)
public class TreeNode {
    private TreeNode parent;
    private List<TreeNode> children;
}

@Data
@AutoMapper(target = TreeNode.class, cycleAvoiding = true)
public class TreeNodeDto {
    private TreeNodeDto parent;
    private List<TreeNodeDto> children;
}
```

--------------------------------

### Define Map Models

Source: https://www.mapstruct.plus/guide/map-to-class.html

Annotate target classes with @AutoMapMapper to enable automatic conversion from Map structures.

```java
@AutoMapMapper
@Data
public class MapModelA {

    private String str;
    private int i1;
    private Long l2;
    private MapModelB mapModelB;

}
```

```java
@AutoMapMapper
@Data
public class MapModelB {

    private Date date;

}
```

--------------------------------

### Perform Map to Object Conversion

Source: https://www.mapstruct.plus/guide/map-to-class.html

Use the Converter bean to map a Map<String, Object> to a target class instance.

```java
@SpringBootTest
public class QuickStartTest {

    @Autowired
    private Converter converter;

    @Test
    public void test() {
        Map<String, Object> mapModel1 = new HashMap<>();
        mapModel1.put("str", "1jkf1ijkj3f");
        mapModel1.put("i1", 111);
        mapModel1.put("l2", 11231);

        Map<String, Object> mapModel2 = new HashMap<>();
        mapModel2.put("date", DateUtil.parse("2023-02-23 01:03:23"));

        mapModel1.put("mapModelB", mapModel2);

        final MapModelA mapModelA = converter.convert(mapModel1, MapModelA.class);
        System.out.println(mapModelA);  // MapModelA(str=1jkf1ijkj3f, i1=111, l2=11231, mapModelB=MapModelB(date=2023-02-23 01:03:23))
    }
}
```

--------------------------------

### Converter API Methods

Source: https://www.mapstruct.plus/guide/converter-api.html

Methods provided by the Converter class to handle various type conversion scenarios including object-to-object, collection-to-collection, and map-to-object.

```APIDOC
## Converter API Methods

### Description
The Converter class provides runtime methods to execute conversion logic between different types.

### Methods

- **convert(S source, Class<T> targetType)**
  - Description: Converts a source object to a new instance of the target type.

- **convert(S source, T target)**
  - Description: Converts properties from the source object into an existing target object, returning the modified target.

- **convert(List<S> source, Class<T> targetType)**
  - Description: Converts a list of source objects into a list of target type objects.

- **convert(Map<String, Object> map, Class<T> target)**
  - Description: Converts a Map<String, Object> into an instance of the target type.
```

--------------------------------

### Configure Number Format Mapping

Source: https://www.mapstruct.plus/guide/class-convert.html

Use the numberFormat attribute in @AutoMapping to specify formats supported by java.text.DecimalFormat for numeric types.

```java
@Data
@AutoMapper(target = OrderEntity.class)
public class Order {

    @AutoMapping(numberFormat = "$0.00")
    private BigDecimal orderPrice;

    @AutoMapping(numberFormat = "$0.00")
    private Integer goodsNum;
    
}
```

```java
@Data
@AutoMapper(target = Order.class)
public class OrderEntity {

    @AutoMapping(numberFormat = "$0.00")
    private String orderPrice;

    @AutoMapping(numberFormat = "$0.00")
    private String goodsNum;
    
}
```

--------------------------------

### Generated Mapping Logic

Source: https://www.mapstruct.plus/guide/cycle-avoiding.html

The generated conversion method utilizing CycleAvoidingMappingContext to prevent infinite recursion.

```java
public TreeNodeDto convert(TreeNode arg0, CycleAvoidingMappingContext arg1) {
    TreeNodeDto target = arg1.getMappedInstance(arg0, TreeNodeDto.class);
    if (target != null) {
        return target;
    }

    if (arg0 == null) {
        return null;
    }

    TreeNodeDto treeNodeDto = new TreeNodeDto();

    arg1.storeMappedInstance(arg0, treeNodeDto);

    treeNodeDto.setParent(demoConvertMapperAdapterForCycleAvoiding.iglm_TreeNodeToTreeNodeDto(arg0.getParent(), arg1));
    treeNodeDto.setChildren(
        demoConvertMapperAdapterForCycleAvoiding.iglm_TreeNodeToTreeNodeDto(arg0.getChildren(), arg1));

    return treeNodeDto;
}
```

--------------------------------

### Define Custom Conversion Methods

Source: https://www.mapstruct.plus/guide/class-convert.html

Combine @Named and qualifiedByName to specify complex conversion logic defined in a separate class referenced by the uses attribute.

```java
@Component
@Named("TitleTranslator")
public class Titles {

    @Named("EnglishToFrench")
    public String translateTitleEF(String title) {
        if ("One Hundred Years of Solitude".equals(title)) {
            return "Cent ans de solitude";
        }
        return "Inconnu et inconnu";
    }

    @Named("FrenchToEnglish")
    public String translateTitleFE(String title) {
        if ("Cent ans de solitude".equals(title)) {
            return "One Hundred Years of Solitude";
        }
        return "Unknown";
    }

}
```

```java
@Data
@AutoMapper(target = FrenchRelease.class, uses = Titles.class)
public class EnglishRelease {

    @AutoMapping(qualifiedByName = "EnglishToFrench")
    private String title;

}
```

```java
@Data
@AutoMapper(target = EnglishRelease.class, uses = Titles.class)
public class FrenchRelease {

    @AutoMapping(qualifiedByName = "FrenchToEnglish")
    private String title;

}
```

--------------------------------

### Execute Custom Java Expressions

Source: https://www.mapstruct.plus/guide/class-convert.html

Use the expression attribute to inject raw Java code into the mapping logic. Note that syntax is not validated during generation.

```java
@AutoMapper(target = UserDto.class)
public class User {

    @AutoMapping(target = "educations", expression = "java(java.lang.String.join(",", source.getEducationList()))")
    private List<String> educationList;

}
```

--------------------------------

### Set Default Values for Null Properties

Source: https://www.mapstruct.plus/guide/class-convert.html

Use the defaultValue attribute to provide a fallback value when the source property is null.

```java
@Data
@AutoMapper(target = DefaultVo.class)
public class DefaultDto {

    @AutoMapping(defaultValue = "18")
    private Integer i;

    @AutoMapping(defaultValue = "1.32")
    private Double d;

    @AutoMapping(defaultValue = "true")
    private Boolean b;

}
```

--------------------------------

### Configure Multiple Target Classes for a Source Class

Source: https://www.mapstruct.plus/guide/multiple-class-convert.html

Use the `@AutoMappers` annotation to specify multiple target classes for a single source class. This is useful when a source object needs to be converted into different DTOs or VOs.

```java
@Data
@AutoMappers({
    @AutoMapper(target = UserDto.class),
    @AutoMapper(target = UserVO.class)
})
public class User {
    // fields
}
```

--------------------------------

### Integrate Custom Mapping Interfaces

Source: https://www.mapstruct.plus/guide/class-convert.html

MapStruct Plus automatically references custom MapStruct mappers defined via the @Mapper annotation when they are available.

```java
@AutoMapper(target = CarDto.class)
@Data
public class Car {
    private Tyre tyre;
}
```

```java
@Data
public class CarDto {
    private TyreDTO tyre;
}
```

```java
@Mapper(componentModel = MappingConstants.ComponentModel.SPRING)
public interface TyreMapper {

    TyreDTO tyreToTyreDTO(Tyre tyre);

    Tyre tyreDtoToTyre(TyreDTO tyreDTO);

}
```

--------------------------------

### Specify Enums for Cross-Module Support

Source: https://www.mapstruct.plus/guide/enum-convert.html

When enums and their usage are in different modules, specify the dependent enums annotated with `@AutoEnumMapper` in the `useEnums` attribute of `@AutoMapper`.

```java
@AutoMapper(target = TargetDto.class, useEnums = {Enum1.class, Enum2.class})
public class SourceClass {
    // ...
}
```

--------------------------------

### Annotate Enum for Automatic Conversion

Source: https://www.mapstruct.plus/guide/enum-convert.html

Add `@AutoEnumMapper` to your enum and specify the unique field name. Ensure the enum and its usage are in the same module.

```java
@Getter
@AllArgsConstructor
@AutoEnumMapper("state")
public enum GoodsStateEnum {
    ENABLED(1, "启用"),
    DISABLED(0, "禁用");

    private final Integer state;
    private final String desc;

}
```

--------------------------------

### Ignore Properties During Mapping

Source: https://www.mapstruct.plus/guide/class-convert.html

Set ignore to true within @AutoMapping to exclude specific fields from the conversion process.

```java
@AutoMapper(target = CarDto.class)
@Data
public class Car {

    @AutoMapping(target = "wheels", ignore = true)
    private Wheels wheels;
    
}
```

--------------------------------

### Target DTO for Enum Field

Source: https://www.mapstruct.plus/guide/enum-convert.html

The target DTO class with the corresponding field type for the enum conversion.

```java
@Data
public class GoodsVo {

    private Integer state;

}
```

--------------------------------

### Handle Immutable Types in MapStruct Plus

Source: https://www.mapstruct.plus/guide/class-convert.html

When a type is immutable, the default behavior of `T convert(S source, @MappingTarget T target)` might be problematic. Using the `Immutable` annotation marks a class as immutable, rendering `@MappingTarget` ineffective and resulting in the target object being returned directly.

```java
public T convert(S source, @MappingTarget T target) {
    return target;
}
```

--------------------------------

### Map Enum Field in Source Class

Source: https://www.mapstruct.plus/guide/enum-convert.html

Use `@AutoMapper` to map the enum field from the source class to the target DTO. `reverseConvertGenerate` is set to false to disable reverse mapping generation for this specific mapping.

```java
@Data
@AutoMapper(target = GoodsVo.class, reverseConvertGenerate = false)
public class Goods {

    private GoodsStateEnum state;

}
```
Tokens:
Raw