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 "<CLASS_NAME>Impl";
    //  指定生成实现类的包名。默认当前包
    String implementationPackage() default "<PACKAGE_NAME>";
    // 引入一个用 {@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<? extends Annotation> mappingControl() default MappingControl.class;
    // 如果没有与枚举匹配的映射，则生成的代码应抛出异常。
    Class<? extends Exception> 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<? extends Annotation>[] 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<? extends Annotation>[] 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<? extends Annotation> 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<String>} 和 {@code List<Date>}。

public @interface IterableMapping {
    // 可被 {@link SimpleDateFormat} 处理的日期格式字符串。
    String dateFormat() default "";
    // 可被 {@link DecimalFormat} 处理的十进制格式字符串。
    String numberFormat() default "";
    // 可以指定限定符以帮助选择合适的映射器。
    Class<? extends Annotation>[] qualifiedBy() default {};
    // 一个或多个限定符名称
    String[] qualifiedByName() default {};
    // 指定要在映射方法的结果中使用的元素的类型，以防多重映射方法符合条件。
    Class<?> elementTargetType() default void.class;
    //  当 {@code null} 作为源值传递给此可迭代映射时要应用的策略。
    NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
    // 允许详细控制映射过程
    Class<? extends Annotation> 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 <T extends BaseEntity> T createEntity(@TargetType Class entityClass) {
     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 "<CLASS_NAME>Impl";
    // 指定包名
    String implementationPackage() default "<PACKAGE_NAME>";
    // 集合类型属性的值时应用的策略。
    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<? extends Annotation> mappingControl() default MappingControl.class;
    // 如果没有与枚举匹配的映射，则生成的代码应抛出异常。
    Class<? extends Exception> unexpectedValueMappingException() default IllegalArgumentException.class;
    // 指示是否应禁止在 {@code @Generated} 注释中添加时间戳的标志。
    boolean suppressTimestampInGenerated() default false;
}

@EnumMapping

@EnumMapping 配置两种枚举类型之间的映射。

public @interface EnumMapping {
    // 指定应该用于枚举之间的隐式映射的名称转换策略。
    String nameTransformationStrategy() default "";
    // 应该在适当的名称转换策略上传递的配置。
    String configuration() default "";
    // 应该在生成的代码中使用的异常
    Class<? extends Exception> 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 {
           /**
         * 控制映射，允许从源类型到目标类型的类型转换
         * <p>
         * Java 通常直接支持类型转换。"toString()"就是这样一个例子，
         * 它允许将例如 {@link java.lang.Number} 类型映射到 {@link java.lang.String}。
         * <p>
         * 请参阅 MapStruct 指南了解更多信息。
         *
         * @从 1.4 开始
         */
        BUILT_IN_CONVERSION,
          /**
         * 控制从源类型到目标类型的映射，允许通过调用进行映射：
         * <ol>
         * <li>类型转换，传入映射方法</li>
         * <li>映射方法，传入类型转换</li>
         * <li>一个映射方法传入另一个映射方法</li>
         * </ol>
         *
         * @从 1.4 开始
         */
        COMPLEX_MAPPING,
        // 如果源类型和目标类型是相同的类型，MapStruct 将不会执行不再有任何映射，并将目标直接分配给源。
        // 一个例外是来自包 {@code java} 的类型，它们将始终直接映射。
        DIRECT,
        // 映射方法可以是自定义引用的映射方法，也可以是内置的 MapStruct映射方法。
        MAPPING_METHOD;

        private Use() {
        }
    }
}

@NoComplexMapping

禁用复杂映射，必须使用方法或内置转换方式构成的映射。