Mapstruct项目中如何全局按字段名忽略指定目标字段？

针对你遇到的「需要忽略DB Model中version这类通用字段，但又不想全局关闭未映射目标的警告/错误」的问题，结合你当前使用的Mapstruct 1.3.1.Final以及计划升级到1.4.1.Final的情况，提供以下几个可行的优雅方案：

方案1：使用@MapperConfig共享忽略配置（兼容1.3.x和1.4.x） #

这个方案不需要升级版本，能在现有1.3.1中直接使用：

1. 创建一个全局的映射配置类，在其中统一定义需要忽略的通用字段：

@MapperConfig
public interface GlobalMappingConfig {
    @Mappings({
        @Mapping(target = "version", ignore = true),
        // 可按需添加其他通用忽略字段，比如createTime、updateTime等
    })
    void ignoreCommonFields(); // 空方法仅用于承载配置逻辑
}

2. 在你的每个Mapper接口上，通过config属性继承这个全局配置：

@Mapper(config = GlobalMappingConfig.class)
public interface UserMapper {
    User toDbModel(UserDto dto);
    // 其他映射方法...
}

这样所有继承该配置的Mapper都会自动忽略version字段，无需在每个映射方法中重复写@Mapping(target = "version", ignore = true)，同时全局的unmappedTargetPolicy依然生效，不会漏掉重要属性的映射检查。

方案2：使用@MappingIgnore注解（仅1.4.x及以上可用） #

如果你升级到1.4.1.Final，这个是最简洁高效的方案：

直接在DB Model的version字段上添加Mapstruct的@MappingIgnore注解，这样所有映射到该Model的Mapper都会自动忽略这个字段，完全不需要在Mapper中做任何配置：

public class User {
    private Long id;
    private String username;
    
    @MappingIgnore // 全局标记忽略该字段的映射
    private Integer version;
    
    // getter/setter方法...
}

这个方案的优势是一劳永逸，所有涉及该Model的映射都会自动忽略version，同时全局的未映射目标检查依然正常工作，完美平衡了便捷性和严谨性。

方案3：结合Profiles实现环境差异化配置（进阶） #

如果你希望在开发环境用ERROR级别严格检查，而测试/生产环境放宽为WARN，同时避免无关警告干扰，可以结合Maven/Gradle的Profiles来动态调整Mapstruct的参数：

以Maven为例，在pom.xml中配置：

<profiles>
    <profile>
        <id>dev</id>
        <properties>
            <mapstruct.unmappedTargetPolicy>ERROR</mapstruct.unmappedTargetPolicy>
        </properties>
    </profile>
    <profile>
        <id>prod</id>
        <properties>
            <mapstruct.unmappedTargetPolicy>WARN</mapstruct.unmappedTargetPolicy>
        </properties>
    </profile>
</profiles>

然后配合方案1或方案2处理version字段的忽略，这样在开发环境启用ERROR级别时，只会收到真正遗漏的重要属性的错误提示，不会被version这类通用字段的警告干扰。

总结 #

• 若暂时不升级版本，优先选择方案1，通过全局配置类统一管理忽略字段；
• 若计划升级到1.4.1，强烈推荐方案2，直接在Model字段上加注解，实现最简洁的全局忽略；
• 进阶场景可结合方案3的Profiles配置，实现不同环境的差异化检查策略。

内容的提问来源于stack exchange，提问作者rav137