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