MapStruct系列（10）-注解汇总大全
文章目录
前言@Mapper@Mapping@Mappings@BeforeMapping @AfterMapping@BeanMapping@InheritConfiguration @InheritInverseConfiguration@IterableMapping@ValueMapping @ValueMappings@SubclassMapping @SubclassMappings@TargetType@Named@MapperConfig@EnumMapping@DecoratedWith@Context@Condition@DeepClone@MappingControl @MappingControls@NoComplexMapping
前言
MapStruct提供了很多注解来，之前我们也进行了一些案例使用，接下来，汇总一下这些注解的作用。
@Mapper
@Mapper将接口或抽象类标记为映射器，并自动生成映射实现类代码。
public @interface Mapper {
// 引入其他其他映射器
Class[] uses() default {};
// 将类import 到生成的实现类中
// 可以使用 {@link mapping#expression（）}表达式中引用这些类型，{@link Mapping#defaultExpression（）}使用他们简单的名字，而不是完全限定的名字。
Class[] imports() default {};
// 源类型未被映射时的策略，默认忽略
ReportingPolicy unmappedSourcePolicy() default ReportingPolicy.IGNORE;
// 目标类型未被映射时的策略，默认警告
ReportingPolicy unmappedTargetPolicy() default ReportingPolicy.WARN;
// 转换存在精度损失的的策略
ReportingPolicy typeConversionPolicy() default ReportingPolicy.IGNORE;
// 指定生成的映射器应该使用的组件模型，比如Spring bean、CDI等
String componentModel() default "default";
// 指定实现类的名称。默认加上Impl 后缀
String implementationName() default "
// 指定生成实现类的包名。默认当前包
String implementationPackage() default "
// 引入一个用 {@link MapperConfig} 注解的配置
Class config() default void.class;
// 集合类型属性的值时应用的策略。
CollectionMappingStrategy collectionMappingStrategy() default CollectionMappingStrategy.ACCESSOR_ONLY;
// 当 {@code null} 作为源参数值传递给此映射器的方法时要应用的策略。
NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
// 当 {@code null} 作为源参数值传递给 {@link IterableMapping} 时应用的策略
NullValueMappingStrategy nullValueIterableMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
// 当 {@code null} 作为源参数值传递给 {@link MapMapping} 时应用的策略
NullValueMappingStrategy nullValueMapMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
// 当源属性为 {@code null} 或不存在时应用的策略。
NullValuePropertyMappingStrategy nullValuePropertyMappingStrategy() default NullValuePropertyMappingStrategy.SET_TO_NULL;
// 用于在接口中应用原型方法的方法级配置注解的策略
MappingInheritanceStrategy mappingInheritanceStrategy() default MappingInheritanceStrategy.EXPLICIT;
// 确定何时对 bean 映射的源属性值进行空检查。
NullValueCheckStrategy nullValueCheckStrategy() default NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
// 确定在使用 {@link SubclassMapping} 时如何处理超类的缺失实现。
SubclassExhaustiveStrategy subclassExhaustiveStrategy() default SubclassExhaustiveStrategy.COMPILE_ERROR;
// 确定是使用字段注入还是构造函数注入
InjectionStrategy injectionStrategy() default InjectionStrategy.FIELD;
// 是否禁用自动生成子映射方法
boolean disableSubMappingMethodsGeneration() default false;
// 构建器信息
Builder builder() default @Builder;
// 允许详细控制映射过程。
Class mappingControl() default MappingControl.class;
// 如果没有与枚举匹配的映射，则生成的代码应抛出异常。
Class unexpectedValueMappingException() default IllegalArgumentException.class;
// 指示是否应禁止在 {@code @Generated} 注释中添加时间戳的标志。
boolean suppressTimestampInGenerated() default false;
}
@Mapping
@Mapping用于配置属性或枚举常量的映射关系。
public @interface Mapping {
// JavaBeans 规范定义的目标帝乡配置属性的名称
String target();
// 用于此映射的源
String source() default "";
// 可被 {@link SimpleDateFormat} 处理的日期格式字符串。
String dateFormat() default "";
// 可被 {@link DecimalFormat} 处理的十进制格式字符串。
String numberFormat() default "";
// 一个常量 {@link String} 将基于它来设置指定的目标属性。
String constant() default "";
// 一个表达式 {@link String} 将基于它来设置指定的目标属性。
String expression() default "";
// 一个 defaultExpression {@link String}，基于它来设置指定的目标属性， 当且仅当指定的源属性为空时。
String defaultExpression() default "";
// 通过 {@link #target()} 指定的属性是否应该被生成的映射方法忽略。
boolean ignore() default false;
// 可以指定限定符以帮助选择合适的映射器。
Class[] qualifiedBy() default {};
// 一个或多个限定符名称
String[] qualifiedByName() default {};
// 指定在多个映射方法符合条件时要使用的映射方法的结果类型。
Class resultType() default void.class;
// 映射属性的依赖关系
String[] dependsOn() default {};
// 在源属性为 {@code null} 的情况下设置的默认值。
String defaultValue() default "";
// 确定何时对 bean 映射的源属性值进行空检查。
NullValueCheckStrategy nullValueCheckStrategy() default NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
// {@code null} 作为源属性值或源属性传递时应用的策略
NullValuePropertyMappingStrategy nullValuePropertyMappingStrategy() default NullValuePropertyMappingStrategy.SET_TO_NULL;
}
@Mappings
@Mappings 用于声明多个@Mapping。
public @interface Mappings {
Mapping[] value();
}
@BeforeMapping @AfterMapping
@BeforeMapping和@AfterMapping 标记在映射方法开始或结束后时需要调用的方法，也就是可以在映射开始、结束后调用。
可以在映射前后做一些自定义操作，类似AOP中的切面。
@BeanMapping
@BeanMapping配置两种bean类型之间的映射。
public @interface BeanMapping {
// 指定在多个工厂方法符合条件时使用的工厂方法的结果类型，
Class resultType() default void.class;
// 指定限定符以帮助选择合适的工厂方法
Class[] qualifiedBy() default {};
// 使用限定符名称查找
String[] qualifiedByName() default {};
// 当 {@code null} 作为源值传递给此映射的方法时要应用的策略。
NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
// {@code null} 作为源属性值或源属性传递时应用的策略
NullValuePropertyMappingStrategy nullValuePropertyMappingStrategy() default NullValuePropertyMappingStrategy.SET_TO_NULL;
// 如何做空检查策略
NullValueCheckStrategy nullValueCheckStrategy() default NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
// 确定在使用 {@link SubclassMapping} 时如何处理超类缺失。
SubclassExhaustiveStrategy subclassExhaustiveStrategy() default SubclassExhaustiveStrategy.COMPILE_ERROR;
// 默认忽略所有映射。所有映射都必须手动定义。不会发生自动映射。
boolean ignoreByDefault() default false;
// 未映射的源属性将被忽略。
String[] ignoreUnmappedSourceProperties() default {};
// 如何报告映射的目标类型的未映射属性。
ReportingPolicy unmappedTargetPolicy() default ReportingPolicy.WARN;
// 指定构建者
Builder builder() default @Builder;
// 允许详细控制映射过程。
Class mappingControl() default MappingControl.class;
}
@InheritConfiguration @InheritInverseConfiguration
inherit是继承的意思，Inverse是反转的意思。
@InheritConfiguration 可以继承其他映射方法上的配置（@Mapping、@IterableMapping 、 Mapper#config()等方式上的配置）。
public @interface InheritConfiguration {
/**
* 要从中继承映射的映射方法的名称
*/
String name() default "";
}
@InheritInverseConfiguration是反向隐射继承，也就是对继承的配置进行逆向映射。
public @interface InheritInverseConfiguration{
/**
* 要从中继承映射的映射方法的名称
*/
String name() default "";
}
@IterableMapping
@IterableMapping用于配置两个几个类似类型之间的映射，例如 {@code List
public @interface IterableMapping {
// 可被 {@link SimpleDateFormat} 处理的日期格式字符串。
String dateFormat() default "";
// 可被 {@link DecimalFormat} 处理的十进制格式字符串。
String numberFormat() default "";
// 可以指定限定符以帮助选择合适的映射器。
Class[] qualifiedBy() default {};
// 一个或多个限定符名称
String[] qualifiedByName() default {};
// 指定要在映射方法的结果中使用的元素的类型，以防多重映射方法符合条件。
Class elementTargetType() default void.class;
// 当 {@code null} 作为源值传递给此可迭代映射时要应用的策略。
NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
// 允许详细控制映射过程
Class elementMappingControl() default MappingControl.class;
}
@ValueMapping @ValueMappings
@ValueMapping 配置源常量值到目标常量值的映射，支持枚举到枚举，@ValueMappings就是可以写多个@ValueMapping 。
public @interface ValueMapping {
String source();
String target();
}
public @interface ValueMappings {
ValueMapping[] value();
}
@SubclassMapping @SubclassMappings
@ValueMapping 配置映射子类，也就是参数和目标对象为父类时，执行其子类的映射关系，@SubclassMappings就是可以写多个@SubclassMapping。
public @interface SubclassMapping {
// 要映射的子类
Class source();
// 要映射到的子类
Class target();
}
public @interface SubclassMappings {
SubclassMapping[] value();
}
@TargetType
@TargetType可以在自定义映射方法的参数中声明目标对象的类型。比如返回类型为泛型，这个时候可以在参数中指定目标的类型。
不能将多个参数声明为{@code TargetType},并且该参数必须是{@link Class}类型或者它的超类型。
public class EntityFactory {
public
return // ... custom factory logic
}
}
@Named
@Named可以给映射方法取名，然后通过限定符直接使用名称绑定映射方法。
public @interface Named {
// 限定注解元素的名称
String value();
}
@MapperConfig
将类或接口标记为配置，允许在多个映射器类之间共享通用配置。
public @interface MapperConfig {
// 使用其他的映射器
Class[] uses() default {};
// 将类import 到生成的实现类中
// 可以使用 {@link mapping#expression（）}表达式中引用这些类型，{@link Mapping#defaultExpression（）}使用他们简单的名字，而不是完全限定的名字。
Class[] imports() default {};
// 映射的源类型的存在未映射属性应该如何报告
ReportingPolicy unmappedSourcePolicy() default ReportingPolicy.IGNORE;
// 映射的目标类型存在未映射属性应该如何映射
ReportingPolicy unmappedTargetPolicy() default ReportingPolicy.WARN;
// 存在精度损失，如何报告
ReportingPolicy typeConversionPolicy() default ReportingPolicy.IGNORE;
// 映射器组件模型
String componentModel() default "default";
// 指定实现类的名称。默认后缀为Impl
String implementationName() default "
// 指定包名
String implementationPackage() default "
// 集合类型属性的值时应用的策略。
CollectionMappingStrategy collectionMappingStrategy() default CollectionMappingStrategy.ACCESSOR_ONLY;
// 当 {@code null} 作为源参数值传递给此映射器的方法时要应用的策略。
NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
// 当 {@code null} 作为源参数值传递给 {@link IterableMapping} 时应用的策略
NullValueMappingStrategy nullValueIterableMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
// 当 {@code null} 作为源参数值传递给 {@link MapMapping} 时应用的策略
NullValueMappingStrategy nullValueMapMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
// 当源属性为 {@code null} 或不存在时应用的策略。
NullValuePropertyMappingStrategy nullValuePropertyMappingStrategy() default NullValuePropertyMappingStrategy.SET_TO_NULL;
// 用于在接口中应用原型方法的方法级配置注解的策略
MappingInheritanceStrategy mappingInheritanceStrategy() default MappingInheritanceStrategy.EXPLICIT;
// 确定何时对 bean 映射的源属性值进行空检查。
NullValueCheckStrategy nullValueCheckStrategy() default NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
// 确定在使用 {@link SubclassMapping} 时如何处理超类的缺失实现。
SubclassExhaustiveStrategy subclassExhaustiveStrategy() default SubclassExhaustiveStrategy.COMPILE_ERROR;
// 确定是使用字段注入还是构造函数注入
InjectionStrategy injectionStrategy() default InjectionStrategy.FIELD;
// 是否禁用自动生成子映射方法
boolean disableSubMappingMethodsGeneration() default false;
// 构建器信息
Builder builder() default @Builder;
// 允许详细控制映射过程。
Class mappingControl() default MappingControl.class;
// 如果没有与枚举匹配的映射，则生成的代码应抛出异常。
Class unexpectedValueMappingException() default IllegalArgumentException.class;
// 指示是否应禁止在 {@code @Generated} 注释中添加时间戳的标志。
boolean suppressTimestampInGenerated() default false;
}
@EnumMapping
@EnumMapping 配置两种枚举类型之间的映射。
public @interface EnumMapping {
// 指定应该用于枚举之间的隐式映射的名称转换策略。
String nameTransformationStrategy() default "";
// 应该在适当的名称转换策略上传递的配置。
String configuration() default "";
// 应该在生成的代码中使用的异常
Class unexpectedValueMappingException() default IllegalArgumentException.class;
}
@DecoratedWith
Decorated是装饰的意思， @DecoratedWith指定要应用于生成的映射器的装饰器。
public @interface DecoratedWith {
// 装饰器类型。必须是一个抽象类。
Class value();
}
@Context
将方法的参数标记为映射上下文。此类参数传递给其他映射方法。
@Condition
@Condition将方法标记为检查方法，以检查 bean 中的属性是否存在等检查。检查方法必须返回 {@code boolean}。
public class PresenceCheckUtils {
@Condition
public static boolean isNotEmpty(String value) {
return value != null && !value.isEmpty();
}
}
@DeepClone
将源类型克隆到目标类型（假设源和目标属于同一类型）。
@MappingControl @MappingControls
@MappingControl 控制源和目标之间的映射方式。
@Retention(RetentionPolicy.CLASS)
@Repeatable(MappingControls.class)
@Target({ElementType.ANNOTATION_TYPE})
@MappingControls({@MappingControl(MappingControl.Use.DIRECT), @MappingControl(MappingControl.Use.BUILT_IN_CONVERSION), @MappingControl(MappingControl.Use.MAPPING_METHOD), @MappingControl(MappingControl.Use.COMPLEX_MAPPING)})
public @interface MappingControl {
MappingControl.Use value();
public static enum Use {
/**
* 控制映射，允许从源类型到目标类型的类型转换
*
* Java 通常直接支持类型转换。“toString()”就是这样一个例子，
* 它允许将例如 {@link java.lang.Number} 类型映射到 {@link java.lang.String}。
*
* 请参阅 MapStruct 指南了解更多信息。
*
* @从 1.4 开始
*/
BUILT_IN_CONVERSION,
/**
* 控制从源类型到目标类型的映射，允许通过调用进行映射：
*
- 类型转换，传入映射方法
- 映射方法，传入类型转换
- 一个映射方法传入另一个映射方法
*
*
*
*
*
* @从 1.4 开始
*/
COMPLEX_MAPPING,
// 如果源类型和目标类型是相同的类型，MapStruct 将不会执行不再有任何映射，并将目标直接分配给源。
// 一个例外是来自包 {@code java} 的类型，它们将始终直接映射。
DIRECT,
// 映射方法可以是自定义引用的映射方法，也可以是内置的 MapStruct映射方法。
MAPPING_METHOD;
private Use() {
}
}
}
@NoComplexMapping
禁用复杂映射，必须使用方法或内置转换方式构成的映射。