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

禁用複雜對映，必須使用方法或內建轉換方式構成的對映。