SuperAPI AI Directory

mapstruct-plus

Coding & development

View repository

Updated 10-15 23:43

About this skill

MapStruct Plus Usage Guide

MapStruct Plus is an enhancement tool for MapStruct, based on the JSR 269 annotation processor, which automatically generates Mapper interfaces through annotations. Core advantage: just add a single @AutoMapper annotation to a class, and bidirectional conversion code will be automatically generated, with no need to hand-write Mapper interfaces.

Trigger conditions: When users need the following operations in a Java/Spring Boot project, please actively activate this skill:

  • Perform object conversion between two Java classes (such as DTO <-> Entity, VO <-> DTO)
  • Use annotations such as @AutoMapper, @AutoMapping, @AutoMappers
  • Configure the mapstruct-plus dependency and annotation processor
  • Use Converter to perform object conversion operations
  • Handle scenarios such as enum conversion, Map-to-object, circular references
  • Resolve mapstruct-plus-related compile-time or runtime issues
  • Mention keywords such as BeanUtils.copyProperties, ModelMapper, object copying, type conversion, DTO conversion

Important: MapStruct Plus already embeds MapStruct, so do not introduce the MapStruct dependency again to avoid version conflicts.

Quick Start

1. Add dependency

SpringBoot environment(recommended):

<properties>
    <mapstruct-plus.version>最新版本</mapstruct-plus.version>
</properties>
<dependencies>
    <dependency>
        <groupId>io.github.linpeilie</groupId>
        <artifactId>mapstruct-plus-spring-boot-starter</artifactId>
        <version>${mapstruct-plus.version}</version>
    </dependency>
</dependencies>

Annotation processor configuration(must be added in maven-compiler-plugin):

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.8.1</version>
    <configuration>
        <annotationProcessorPaths>
            <path>
                <groupId>io.github.linpeilie</groupId>
                <artifactId>mapstruct-plus-processor</artifactId>
                <version>${mapstruct-plus.version}</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

Working with Lombok(lombok >= 1.18.16), you need to additionally add lombok-mapstruct-binding:

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

Non-SpringBoot environment: change the dependency to mapstruct-plus(not the starter), add the @ComponentModelConfig(componentModel = "default") configuration class, and use new Converter() to create an instance.

2. Declare the mapping relationship

Add to any one class @AutoMapper:

@AutoMapper(target = UserDto.class)
@Data
public class User {
    private String username;
    private int age;
}

3. Perform conversion

// SpringBoot - 自动注入
@Autowired
private Converter converter;

UserDto dto = converter.convert(user, UserDto.class);
List<UserDto> dtoList = converter.convert(userList, UserDto.class);
User updated = converter.convert(dto, existingUser);  // 更新已有对象

Core annotations quick reference

Annotation Location Purpose Core attributes
@AutoMapper Class Declare conversion relationship target(required), uses, reverseConvertGenerate, cycleAvoiding
@AutoMappers Class Multi-target conversion Contains multiple @AutoMapper
@AutoMapping Field Custom property mapping target, source, dateFormat, numberFormat, ignore, expression, qualifiedByName
@AutoMappings Field Multiple mapping rules Contains multiple @AutoMapping, distinguished by targetClass Distinguish
@AutoEnumMapper Enum class Automatic enum conversion value(enum unique identifier field name)
@AutoMapMapper Class Map to object No attributes
@ReverseAutoMapping Field Reverse mapping configuration source(target class property), target(source class property)
@MapperConfig Class (global) Module configuration mapperPackage, unmappedTargetPolicy, nullValueMappingStrategy
@ComponentModelConfig Class Component model componentModel(set "default" for non-SpringBoot)
@Immutable Class Immutable marker After marking, the update method does not modify target

For the complete attribute definitions of the annotations, please refer to references/annotations.md

Common scenario examples

Custom property mapping

@AutoMapper(target = CarDto.class)
@Data
public class Car {
    @AutoMapping(target = "seat")              // 不同属性名
    private SeatConfiguration seatConfiguration;

    @AutoMapping(dateFormat = "yyyy-MM-dd HH:mm:ss")  // 日期格式
    private LocalDateTime orderTime;

    @AutoMapping(numberFormat = "$0.00")        // 数字格式
    private BigDecimal price;

    @AutoMapping(ignore = true)                // 忽略映射
    private String internal;

    @AutoMapping(defaultValue = "0")           // null时默认值
    private Integer count;

    @AutoMapping(expression = "java(String.join(\",\", source.getList()))")  // 表达式
    private List<String> list;
}

One-to-many conversion

@AutoMappers({
    @AutoMapper(target = UserDto.class),
    @AutoMapper(target = UserVO.class)
})
@Data
public class User {
    @AutoMapping(targetClass = UserDto.class, target = "educations")
    private List<String> educationList;

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

Automatic enum conversion

@AutoEnumMapper("code")
@Getter @AllArgsConstructor
public enum StatusEnum {
    ENABLED(1), DISABLED(0);
    private final Integer code;
}

// 实体中直接用枚举类型,会自动与 code 值互相转换
@AutoMapper(target = GoodsVo.class)
@Data
public class Goods {
    private StatusEnum status;  // 自动转为 Integer
}

Map to object

@AutoMapMapper
@Data
public class ConfigModel {
    private String name;
    private Integer value;
}
// converter.convert(map, ConfigModel.class)

Requires importing hutool-core dependency (version 1.4.0+).

Circular references (tree structures, etc.)

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

Custom converter

@Component
@Named("TitleTranslator")
public class Titles {
    @Named("EnglishToFrench")
    public String toFrench(String title) { ... }
}

@AutoMapper(target = FrenchRelease.class, uses = Titles.class)
@Data
public class EnglishRelease {
    @AutoMapping(qualifiedByName = "EnglishToFrench")
    private String title;
}

Reverse mapping configuration

@AutoMapper(target = Target.class)
@Data
public class Source {
    @AutoMapping(target = "targetName")
    @ReverseAutoMapping(source = "targetName", target = "sourceName")
    private String sourceName;
}

Automatic nested object conversion

When a property is a custom type, as long as that type is also configured with @AutoMapper, it will be converted recursively automatically:

@AutoMapper(target = CarDto.class)
public class Car {
    private Seat seat;  // 自动使用 Seat 的转换器
}

@AutoMapper(target = SeatDto.class)
public class Seat { ... }

Converter API

io.github.linpeilie.Converter Unified conversion entry point:

Method Description
convert(source, TargetClass.class) Create a new target object
convert(source, existingTarget) Update an existing object
convert(list, TargetClass.class) Batch list conversion
convert(source, Class, Consumer) Conversion + post-processing
convert(source, Class, CycleAvoidingMappingContext) Circular-reference-safe conversion
convert(Map, Class) Map to object (requires @AutoMapMapper)

Common issues

Issue Solution
"cannot find converter" Check dependencies/annotation processor, mvn clean compile, check Spring scan packages
"Couldn't retrieve @Mapper" MapStruct dependency conflict, exclude MapStruct from other dependencies
NoSuchMethodError: Adapter Multi-module conflict, configure different adapterPackage
spring-boot-devtools exception Remove this dependency, it modifies the ClassLoader
Generated code location target/generated-sources directory

For the complete troubleshooting guide, see references/troubleshooting.md For the complete annotation properties, see references/annotations.md For configuration details, see references/configuration.md