本文详解如何使用 MapStruct 实现 CustomerSource 到嵌套结构 CustomerAddresses 的零冗余映射，通过自动委托方法和 source = "." 语法消除逐字段声明，同时原生支持单对象到集合的转换，提升类型安全与可维护性。
本文详解如何使用 mapstruct 实现 `customersource` 到嵌套结构 `customeraddresses` 的零冗余映射，通过自动委托方法和 `source = "."` 语法消除逐字段声明，同时原生支持单对象到集合的转换，提升类型安全与可维护性。
在企业级 Java 开发中，DTO（Data Transfer Object）与领域模型之间的对象映射是高频场景。当源对象与目标对象存在深度嵌套、字段同名但路径不同（如 firstname → customer.firstname）或需将单个源对象转为集合（如 CustomerSource → List<address></address>）时，若依赖 @Mapping(target = "customer.firstname", source = "firstname") 逐字段声明，不仅代码冗长，更易因字段新增而遗漏，违背 DRY 原则。
MapStruct 提供了优雅的解决方案：基于方法委托的自动映射与 source = "." 全对象传递语义。以下为完整实践步骤：
✅ 步骤一：定义专用映射方法（无需注解）
在 Mapper 接口中显式声明两个辅助方法，MapStruct 会自动识别并复用它们：
// 将 CustomerSource 映射为嵌套的 CustomerTarget
CustomerAddresses.CustomerTarget toCustomerTarget(CustomerSource customerSource);
// 将 CustomerSource 映射为 Address，并封装为单元素 List
default List<customeraddresses.address> toAddressList(CustomerSource customerSource) {
return Collections.singletonList(toAddress(customerSource));
}
// 单对象到 Address 的基础映射（由 MapStruct 自动生成）
CustomerAddresses.Address toAddress(CustomerSource customerSource);</customeraddresses.address>
? 注意：
toCustomerTarget和toAddress方法签名需严格匹配字段名（大小写敏感），MapStruct 会自动完成同名属性拷贝；toAddressList使用default方法确保编译期可用，且可灵活扩展（如条件生成多地址）。
✅ 步骤二：主映射方法启用全对象委托
在主方法 toTarget 中，利用 source = "." 表示“将整个参数对象作为输入”，交由上述方法处理：
@Mapper
public interface CustomerMapper {
@Mapping(source = ".", target = "customer") // 整个 CustomerSource → CustomerTarget
@Mapping(source = ".", target = "addresses") // 整个 CustomerSource → List<address>
CustomerAddresses toTarget(CustomerSource customer);
// 辅助方法（同上）
CustomerAddresses.CustomerTarget toCustomerTarget(CustomerSource customerSource);
default List<customeraddresses.address> toAddressList(CustomerSource customerSource) {
return Collections.singletonList(toAddress(customerSource));
}
CustomerAddresses.Address toAddress(CustomerSource customerSource);
}</customeraddresses.address>
</address>
✅ 自动生成原理说明
-
@Mapping(source = ".", target = "customer")：触发toCustomerTarget(CustomerSource)方法调用； -
@Mapping(source = ".", target = "addresses")：触发toAddressList(CustomerSource)方法调用； - MapStruct 编译时生成实现类，无反射开销、类型安全、IDE 可导航，且支持
@AfterMapping等生命周期钩子。
⚠️ 注意事项
-
字段一致性要求：
CustomerSource与CustomerTarget/Address的同名字段（如firstname,houseNumber）必须类型兼容，否则需配合@Mapping指定转换逻辑； -
避免循环引用：若
CustomerTarget或Address内部又引用CustomerSource，需用@InheritInverseConfiguration或@Context控制映射方向； -
集合映射进阶：如需一对多（如一个
CustomerSource生成多个Address），可在toAddressList中按业务逻辑构造列表，而非仅singletonList。
✅ 总结
MapStruct 的 source = "." 机制本质是面向对象的映射委托——它将“字段级映射”升维为“对象级协议”，既消除了样板代码，又保留了完全的编译时检查能力。相比手动 expression 或运行时反射方案，该方式性能更高、调试更直观、协作更清晰，是构建健壮数据转换层的推荐实践。
