mapstruct.Mapper|Mapping详解

------------------------------------------------------------------------------------------

org.mapstruct.Mapper 和 org.mapstruct.Mapping 是 MapStruct 框架中的核心注解，用于实现 Java 对象之间的自动映射。MapStruct 是一个代码生成器，通过注解配置生成类型安全、高性能的对象映射代码，避免手动编写繁琐的 setter/getter 转换逻辑。

1. @Mapper 注解

• 作用：标记接口为 MapStruct 映射器，MapStruct 会在编译时为该接口生成实现类，实现对象之间的转换逻辑。
• 常用属性：
  • componentModel：指定映射器的组件模型，如 spring（生成 Spring Bean）、cdi、jsr330 等，便于依赖注入。
  • uses：指定其他映射器类，用于处理复杂类型转换。
  • unmappedTargetPolicy：指定未映射目标属性的处理策略（如报错、警告）。

 

示例：

 

java

 

运行

 

 

 

 

// 声明一个 Spring 管理的映射器
@Mapper(componentModel = "spring", unmappedTargetPolicy = ReportingPolicy.IGNORE)
public interface UserMapper {// 映射方法（由 MapStruct 自动实现）UserDTO toDTO(User user);User toEntity(UserDTO dto);
}

 

2. @Mapping 注解

• 作用：配置源对象与目标对象之间的属性映射关系，解决属性名不一致、类型转换等问题。
• 常用属性：
  • source：源对象的属性名（如 userName）。
  • target：目标对象的属性名（如 name）。
  • dateFormat：日期类型转换的格式（如 yyyy-MM-dd）。
  • expression：通过表达式自定义转换逻辑（如 java: java.util.UUID.randomUUID().toString()）。
  • ignore：是否忽略该属性映射（true 表示不映射）。

 

示例：

 

java

 

运行

 

 

 

 

@Mapper(componentModel = "spring")
public interface OrderMapper {// 基础映射（属性名一致时可省略 @Mapping）@Mapping(source = "orderNo", target = "orderNumber") // 名称不一致时映射@Mapping(source = "createTime", target = "createDate", dateFormat = "yyyy-MM-dd") // 日期格式化@Mapping(target = "id", ignore = true) // 忽略目标属性OrderDTO toDTO(Order order);// 多源对象映射@Mapping(source = "user.name", target = "userName")@Mapping(source = "order.total", target = "amount")OrderDetailDTO toDetailDTO(User user, Order order);
}

 

核心优势

1. 类型安全：编译时检查属性映射是否正确，避免运行时错误。
2. 高性能：生成的代码是普通的 setter/getter 调用，比反射（如 BeanUtils）更快。
3. 可维护性：映射规则集中在接口注解中，无需手动编写转换工具类。

 

使用时需在项目中引入 MapStruct 依赖（以 Maven 为例）：

 

xml

 

 

<dependency><groupId>org.mapstruct</groupId><artifactId>mapstruct</artifactId><version>1.5.5.Final</version>
</dependency>
<dependency><groupId>org.mapstruct</groupId><artifactId>mapstruct-processor</artifactId><version>1.5.5.Final</version><scope>provided</scope>
</dependency>

 

 

通过这两个注解，可快速实现 DO、DTO、VO 等对象之间的转换，大幅简化开发工作。

------------------------------------------------------------------------------------------

org.mapstruct.Mapping属性详解

org.mapstruct.Mapping 是 MapStruct 框架中用于精细控制属性映射规则的核心注解，主要解决源对象与目标对象之间属性名不一致、类型不匹配、格式转换等问题。以下是其常用属性的详细说明及示例：

1. 基础映射属性

source

• 作用：指定源对象的属性名（即被映射的字段）。
• 适用场景：源与目标属性名不同时，明确源字段。
• 示例：
  java

   

  运行

   

   

   

   

  // 源对象有属性 userName，目标对象有属性 name
  @Mapping(source = "userName", target = "name")
  UserDTO toDTO(User user);
  

   
• 注意：
  • 支持嵌套属性（如 source = "user.addr.city"）。
  • 若源属性为集合，可通过索引访问（如 source = "hobbies[0]"）。

target

• 作用：指定目标对象的属性名（即接收映射的字段）。
• 必须搭配：通常与 source 一起使用，定义映射关系。
• 示例：
  java

   

  运行

   

   

   

   

  // 源字段 id 映射到目标字段 userId
  @Mapping(source = "id", target = "userId")
  OrderDTO toDTO(Order order);
  

   

ignore

• 作用：指定是否忽略目标属性（不进行映射）。
• 默认值：false（不忽略）。
• 适用场景：目标属性无需从源对象获取（如自增 ID、默认值字段）。
• 示例：
  java

   

  运行

   

   

   

   

  // 忽略目标对象的 createTime 字段（由目标系统自动生成）
  @Mapping(target = "createTime", ignore = true)
  UserDTO toDTO(User user);
  

   

2. 类型转换属性

dateFormat

• 作用：指定日期 / 时间类型的转换格式（适用于 Date、LocalDate、String 之间的转换）。
• 适用场景：源为 Date 类型，目标为 String 类型（或反之）。
• 示例：
  java

   

  运行

   

   

   

   

  // 源字段 createTime（LocalDateTime）转换为目标字段 createTimeStr（String），格式为 yyyy-MM-dd HH:mm:ss
  @Mapping(source = "createTime", target = "createTimeStr", dateFormat = "yyyy-MM-dd HH:mm:ss")
  OrderDTO toDTO(Order order);
  

   

numberFormat

• 作用：指定数字类型的格式化规则（如保留小数、百分比等）。
• 适用场景：Number 与 String 类型转换，需格式化显示。
• 示例：
  java

   

  运行

   

   

   

   

  // 源字段 price（BigDecimal）转换为目标字段 priceStr（String），保留2位小数
  @Mapping(source = "price", target = "priceStr", numberFormat = "#0.00")
  ProductDTO toDTO(Product product);
  

   

qualifiedByName

• 作用：指定自定义转换方法（通过方法名引用），处理复杂类型转换。
• 使用步骤：
  1. 在映射器接口中定义自定义转换方法，并添加 @Named 注解标记。
  2. 在 @Mapping 中通过 qualifiedByName 引用方法名。
• 示例：
  java

   

  运行

   

   

   

   

  import org.mapstruct.Named;@Mapper(componentModel = "spring")
  public interface UserMapper {// 引用自定义转换方法 "statusConverter"@Mapping(source = "status", target = "statusDesc", qualifiedByName = "statusConverter")UserDTO toDTO(User user);// 自定义转换方法：将数字状态码转为文字描述@Named("statusConverter")default String convertStatus(Integer status) {if (status == 1) return "正常";if (status == 0) return "禁用";return "未知";}
  }
  

   

expression

• 作用：通过 Java 表达式自定义映射逻辑（直接生成代码）。
• 语法：expression = "java(表达式)"，表达式需返回目标属性类型。
• 适用场景：简单逻辑的动态计算（如生成 UUID、拼接字符串）。
• 示例：
  java

   

  运行

   

   

   

   

  // 目标字段 orderSn 由表达式生成（UUID + 时间戳）
  @Mapping(target = "orderSn", expression = "java(java.util.UUID.randomUUID().toString() + System.currentTimeMillis())")
  OrderDTO toDTO(Order order);
  

   
• 注意：表达式中需使用完整类名（如 java.util.UUID 而非 UUID）。

3. 集合与映射属性

collectionMappingStrategy

• 作用：指定集合类型（如 List、Set）的映射策略。
• 可选值：
  • ACCESSOR_ONLY（默认）：通过 getter/setter 操作集合。
  • SETTER_PREFERRED：优先使用 setter 方法。
  • ADDER_PREFERRED：优先使用 add 方法（如 addItem()）。
  • TARGET_IMMUTABLE：目标集合不可变时，创建新集合。
• 示例：
  java

   

  运行

   

   

   

   

  // 对 tags 字段使用 ADDER_PREFERRED 策略（调用 addTag() 而非 setTags()）
  @Mapping(source = "tags", target = "tags", collectionMappingStrategy = CollectionMappingStrategy.ADDER_PREFERRED)
  PostDTO toDTO(Post post);
  

   

mapKeyDateFormat / mapValueDateFormat

• 作用：当映射 Map 类型时，指定 key 或 value 为日期类型的格式化规则。
• 示例：
  java

   

  运行

   

   

   

   

  // Map<Date, String> 映射为 Map<String, String>，key 格式化为 yyyy-MM-dd
  @Mapping(target = "dateMap", mapKeyDateFormat = "yyyy-MM-dd")
  ReportDTO toDTO(Report report);
  

   

4. 其他常用属性

defaultValue

• 作用：当源属性为 null 时，指定目标属性的默认值。
• 示例：
  java

   

  运行

   

   

   

   

  // 若 source 中 age 为 null，目标 age 设为 0
  @Mapping(source = "age", target = "age", defaultValue = "0")
  UserDTO toDTO(User user);
  

   

defaultExpression

• 作用：当源属性为 null 时，通过表达式生成目标属性的默认值（比 defaultValue 更灵活）。
• 示例：
  java

   

  运行

   

   

   

   

  // 若 createTime 为 null，默认值为当前时间
  @Mapping(source = "createTime", target = "createTime", defaultExpression = "java(java.time.LocalDateTime.now())")
  UserDTO toDTO(User user);
  

   

unmappedSourcePolicy / unmappedTargetPolicy

• 作用：指定源 / 目标属性未被映射时的处理策略（覆盖 @Mapper 中的全局配置）。
• 可选值：
  • IGNORE：忽略（默认）。
  • WARN：编译时警告。
  • ERROR：编译时报错（强制检查，推荐生产环境）。
• 示例：
  java

   

  运行

   

   

   

   

  // 若目标字段有未映射的属性，编译时报错
  @Mapping(target = "extra", unmappedTargetPolicy = ReportingPolicy.ERROR)
  UserDTO toDTO(User user);
  

   

总结：常用属性优先级

当多个属性同时使用时，生效优先级为：
expression > qualifiedByName > dateFormat/numberFormat > 默认转换

通过灵活组合这些属性，MapStruct 可应对绝大多数对象映射场景，既保证类型安全，又避免手动编写转换代码的繁琐。

 

------------------------------------------------------------------------------------------

------------------------------------------------------------------------------------------

------------------------------------------------------------------------------------------