MapStruct的常用注解及使用场景

1. @Mapper

作用： 标记接口或抽象类为映射器，自动生成实现类代码，支持配置全局映射策略。关键属性：

componentModel：指定组件模型（如 spring、cdi），用于依赖注入。uses：引入其他映射器或工具类。unmappedTargetPolicy：未映射字段的处理策略（如 IGNORE 或 ERROR）。

使用场景： 定义所有映射方法的入口，适用于任何需要对象转换的场景。示例：

@Mapper(componentModel = "spring", uses = DateUtils.class)

public interface UserMapper {

UserDTO toUserDTO(User user);

}

2. @Mapping

作用： 定义单个字段的映射规则，支持属性名转换、表达式、常量等。关键属性：

source：源对象属性名（支持嵌套路径，如 user.address.city）。target：目标对象属性名。expression：自定义转换逻辑（如调用方法）。constant：固定值映射。ignore：忽略该字段。

使用场景： 字段名不一致、类型转换、动态赋值。示例：

@Mapping(source = "userName", target = "name")

@Mapping(target = "createTime", expression = "java(new Date())")

UserDTO toUserDTO(User user);

3. @Mappings

作用： 组合多个 @Mapping 注解，定义多个字段映射规则。使用场景： 需要同时配置多个字段的映射关系。示例：

@Mappings({

@Mapping(source = "id", target = "userId"),

@Mapping(source = "email", target = "contactInfo")

})

UserDTO toUserDTO(User user);

4. @BeanMapping

作用： 配置整个映射方法的全局策略，如忽略未映射字段或空值处理。关键属性：

ignoreByDefault：忽略所有未显式映射的字段。nullValuePropertyMappingStrategy：空值处理策略（如 SET_TO_NULL）。

使用场景： 需要全局控制映射行为，避免逐个字段配置。示例：

@BeanMapping(ignoreByDefault = true)

UserDTO toUserDTO(User user);

5. @BeforeMapping / @AfterMapping

作用： 在映射前后执行自定义逻辑，如数据预处理或后处理。使用场景： 动态修改源/目标对象、填充额外字段、调用外部服务。示例（格式化日期）：

@BeforeMapping

default void formatDate(User user) {

user.setCreateTime(format(user.getRawDate()));

}

@AfterMapping

default void addStatus(User user, @MappingTarget UserDTO dto) {

dto.setStatus(calculateStatus(user));

}

6. @IterableMapping

作用： 定义集合类型（如 List、Set）元素的映射规则。关键属性：

elementTargetType：目标元素类型。dateFormat：日期格式化。

使用场景： 集合元素类型转换或批量映射。示例：

@IterableMapping(elementTargetType = UserDTO.class)

List toUserDTOList(List users);

7. @MapMapping

作用： 定义 Map 类型的键值映射规则。关键属性：

keyDateFormat / valueDateFormat：键或值的日期格式。mapNullToEmpty：空 Map 处理。

使用场景： Map 结构数据转换，如键值类型转换。示例：

@MapMapping(keyDateFormat = "yyyyMMdd", valueDateFormat = "dd-MM-yyyy")

Map convertMap(Map source);

8. @InheritConfiguration / @InheritInverseConfiguration

作用： 继承正向或逆向映射规则，避免重复配置。使用场景： 双向映射（如 User ↔ UserDTO）时复用配置。示例：

@InheritConfiguration

void updateUserFromDTO(UserDTO dto, @MappingTarget User user);

@InheritInverseConfiguration

UserDTO toUserDTO(User user);

9. @ValueMapping

作用： 处理枚举类型映射，支持名称或值转换。使用场景： 枚举值与字符串或其他枚举的转换。示例：

@ValueMapping(source = "ACTIVE", target = "ENABLED")

StatusDTO toStatusDTO(Status status);

10. @Context

作用： 传递上下文参数（如用户信息、配置），供映射方法使用。使用场景： 需要外部数据参与映射逻辑（如权限校验）。示例：

UserDTO toUserDTO(User user, @Context User currentUser);

11. @Named

作用： 标记自定义方法，供其他映射规则通过 qualifiedByName 引用。使用场景： 复用复杂转换逻辑。示例：

@Named("formatDate")

default String format(Date date) {

return new SimpleDateFormat("yyyy-MM-dd").format(date);

}

@Mapping(target = "date", source = "rawDate", qualifiedByName = "formatDate")

UserDTO toUserDTO(User user);

12. @MapperConfig

作用： 定义全局映射配置，供多个映射器继承。使用场景： 统一配置公共策略（如日期格式、空值处理）。示例：

@MapperConfig(

unmappedTargetPolicy = ReportingPolicy.IGNORE,

uses = DateUtils.class

)

public interface CentralConfig {}

@Mapper(config = CentralConfig.class)

public interface UserMapper extends CentralConfig {}