MapStruct - 注解汇总

mapstruct · 浏览次数 : 0

小编点评

@Mapper 注解用于将接口或抽象类标记为映射器,并自动生成映射实现类代码。它提供了多种属性来配置映射过程,包括: - `uses()`:导入其他映射器类。 - `imports()`:将类型导入到生成的实现类中。 - `unmappedSourcePolicy()`:未映射的源属性的策略,默认为 `Ignored`。 - `unmappedTargetPolicy()`:未映射的目标属性的策略,默认为 `Warn`。 - `typeConversionPolicy()`:精度损失报告策略,默认为 `Ignored`。 - `componentModel()`:组件模型,如Spring bean、CDI等,默认为 `default`。 - `implementationName()`:实现类的名称,默认加上 `Impl` 后缀。 - `implementationPackage()`:实现类的包名,默认为当前包。 - `config()`:注入配置,可以继承其他映射方法上的配置。 - `collectionMappingStrategy()`:集合类型属性值的应用策略,默认为 `ACCESSOR_ONLY`。 以下是一些具体的注解用途: - `@mapping`:用于配置属性或枚举常量的映射关系。 - `@mappings`:用于声明多个@Mapping。 - `@BeforeMapping`、`@AfterMapping`:在映射方法开始或结束后调用的方法。 - `@BeanMapping`:用于配置两种bean类型之间的映射。 - `@ValueMappings`:用于配置源常量值到目标常量值的映射,支持枚举到枚举。 - `@SubclassMapping`:用于配置映射子类。 - `@TargetType`:用于在自定义映射方法的参数中声明目标对象的类型。 - `@Named`:为映射方法命名,通过限定符直接使用名称绑定映射方法。 - `@MapperConfig`:用于标记类或接口作为配置,共享通用配置。 - `@InheritConfiguration`:用于继承其他映射方法的配置。 - `@InheritInverseConfiguration`:用于反向隐射继承。 - `@Iterable_mapping`:用于配置两个类似类型之间的映射。 - `@ValueMappings`:用于配置源常量值到目标常量值的映射,支持枚举到枚举。 - `@SubclassMappings`:用于配置映射子类。 - `@TargetType`:用于在自定义映射方法的参数中声明目标对象的类型。 - `@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 "<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@IterableMappingMapper#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

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

与MapStruct - 注解汇总相似的内容: