@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
禁用复杂映射,必须使用方法或内置转换方式构成的映射。