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 {}