本文介绍如何利用 MapStruct 的自动属性映射机制与 @AfterMapping（或 @BeforeMapping）注解，在保持绝大多数字段默认映射的同时，仅对个别需预/后处理的字段编写自定义逻辑，大幅提升映射代码的简洁性与可维护性。
本文介绍如何利用 mapstruct 的自动属性映射机制与 `@aftermapping`（或 `@beforemapping`）注解，在保持绝大多数字段默认映射的同时，仅对个别需预/后处理的字段编写自定义逻辑，大幅提升映射代码的简洁性与可维护性。
MapStruct 的核心优势之一是约定优于配置：只要源对象与目标对象中字段名相同、类型兼容（或存在隐式转换），MapStruct 会在编译期自动生成对应的赋值代码，无需任何显式 @Mapping 声明。这意味着，面对两个高度相似的 DTO（如仅存在命名差异或少量逻辑转换需求），你完全不必为每个字段手写映射规则。
真正需要干预的，往往只是极少数例外场景——例如某个字段需经函数加工（如格式化、加盐、拼接）、需从上下文注入、或需条件赋值。此时，推荐使用生命周期钩子方法：@AfterMapping（映射完成后执行）或 @BeforeMapping（映射开始前执行）。它们接收已生成的源对象、目标对象（通过 @MappingTarget 标注）及可选参数，让你专注编写“差异化逻辑”，其余字段由框架全自动处理。
以下是一个典型实践示例：
import org.mapstruct.AfterMapping;
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.MappingTarget;
@Mapper
public abstract class DtoMapper {
// 显式声明一个命名不一致的字段映射（如 notDesiredName → desiredName）
@Mapping(target = "desiredName", source = "notDesiredName")
// 声明抽象映射方法（MapStruct 将为其生成实现）
public abstract Dto2 toDto2(Dto1 dto1);
// 仅在此处处理需要定制的字段：somethingThatChanges 需追加 ": changed"
@AfterMapping
protected void interveneWithSomethingThatChanges(
Dto1 dto1,
@MappingTarget Dto2 dto2) {
dto2.somethingThatChanges = dto1.somethingThatChanges + ": changed";
}
}
✅ 关键要点说明：
- @Mapping(target = "desiredName", source = "notDesiredName") 用于处理命名不一致的常规字段，仍属“声明式配置”，但只需写一次；
- @AfterMapping 方法中只编写真正需要干预的逻辑，其他字段（如 somethingThatStaysTheSame）会由 MapStruct 自动完成拷贝；
- @MappingTarget 是必需标注，它告诉 MapStruct：该参数是映射生成的目标实例，而非新创建的对象；
- 方法必须为 protected 或 public，且参数顺序灵活，但必须包含源对象和带 @MappingTarget 的目标对象。
⚠️ 注意事项：
- 若存在多个 @AfterMapping 方法，MapStruct 会按声明顺序依次执行；
- 避免在 @AfterMapping 中修改源对象（除非业务明确要求），因其可能被复用；
- 对于复杂转换（如嵌套对象、集合、空值策略），优先考虑 @ObjectFactory、@IterableMapping 或自定义 @Named 方法，而非在钩子中硬编码；
- 编译时请确保启用了 annotation processing（如 Maven 中配置 mapstruct-processor），否则无法生成实现类。
通过这种“默认自动 + 按需钩子”的组合策略，你既能享受 MapStruct 的零样板映射能力，又能精准控制任意边缘逻辑，真正实现清晰、健壮且易于演进的 DTO 转换层。
