MapStruct自定义注解消除重复@Mapping忽略审计字段

本文介绍如何通过自定义复合注解（如 @ignoreauditmapping）统一管理 createdat、updatedat、createdby、modifiedby 等通用审计字段的忽略逻辑，避免在多个 mapstruct 映射方法中重复书写冗长的 @mapping(ignore = true) 声明，从而显著提升代码的可维护性与可读性。

在实际的 Spring 商业项目中，实体类常常包含 createdAt、updatedAt、createdBy、modifiedBy 等审计字段。这些字段通常由 JPA 或 Spring Data Audit 自动填充，不应从 DTO 或请求对象反向映射回来。然而，如果每个 @Mapping 方法都手动编写十余行 @Mapping(target = "xxx", ignore = true)，代码不仅显得臃肿，还容易因遗漏或拼写错误引发安全漏洞，例如意外覆盖 id 或审计时间字段。

✅ 推荐方案：自定义组合注解（Composed Annotation）
MapStruct 原生支持将多个 @Mapping 注解打包成一个自定义注解——这是目前最简洁、类型安全且对 IDE 最友好的方式。只需定义一次，便可在所有映射方法上复用：

// 审计字段统一忽略注解
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Mapping(target = "createdAt", ignore = true)
@Mapping(target = "updatedAt", ignore = true)
@Mapping(target = "createdBy", ignore = true)
@Mapping(target = "modifiedBy", ignore = true)
public @interface IgnoreAuditMapping {}

⚠️ 注意：该注解必须标注 @Retention(RUNTIME)，否则 MapStruct 在运行时无法读取元数据；同时要确保 @Mapping 中的 target 字段名与实际 POJO 属性严格一致，区分大小写，并且支持点号路径，如 "parentCategory.createdAt"。

随后，在 Mapper 接口中直接应用此注解，再根据需求补充其他特殊忽略项即可：

@Mapper(config = MapperConfiguration.class)
public interface CategoryMapper {
    CategoryDto toDto(Category category);

    @IgnoreAuditMapping
    @Mapping(target = "id", ignore = true)
    @Mapping(target = "quizzes", ignore = true)
    // 支持嵌套路径（自动继承 IgnoreAuditMapping 中的 parentCategory.*）
    @Mapping(target = "parentCategory.id", ignore = true)
    @Mapping(target = "parentCategory.quizzes", ignore = true)
    Category toCategory(CategoryDto categoryDto);

    @IgnoreAuditMapping
    @Mapping(target = "id", ignore = true)
    @Mapping(target = "quizzes", ignore = true)
    @Mapping(target = "parentCategory", ignore = true)       // 全量忽略 parentCategory 对象
    @Mapping(target = "childCategories", ignore = true)
    Category toDomain(CategoryCreationRequest request);
}

? 进阶技巧：扩展可复用性

• 如果不同模块的审计字段存在细微差别（例如部分实体还带有 deletedAt 或 version），完全可以定义多组注解：@IgnoreBaseAuditMapping、@IgnoreFullAuditMapping；
• 结合 @InheritConfiguration 实现配置继承，适用于需要差异化处理 target 的场景——例如某些方法需要映射 id 但忽略其余审计字段；
• 配合 MapStruct 的 @MapperConfig 全局配置，统一设置 unmappedTargetPolicy = ReportingPolicy.IGNORE，可以避免未映射字段报错，但这一配置并不替代语义明确的 ignore = true。

✅ 总结
采用自定义组合注解来处理 MapStruct 中审计字段的重复忽略问题，是目前公认的最佳实践——零侵入、零反射开销、完全兼容编译期代码生成，并天然支持 IDE 的自动补全与静态检查。与抽象父接口或手写 @AfterMapping 方法相比，该方案更轻量、直观，也更易于测试和维护。