mapstruct在映射时通常只在源字段非空时设置目标字段。然而，当需要将目标字段设置为常量，但仅当源字段非空时才应用此常量，否则目标字段应为null时，常规的`@mapping(constant = "...")`无法满足需求。本文将探讨两种实现此条件的策略：利用`@qualifiedbyname`结合自定义方法，以及使用`@expression`配合三元运算符，并分析各自的优缺点，以指导开发者选择最合适的实现方式。
MapStruct默认行为与条件映射挑战
MapStruct是一个强大的代码生成器，用于简化Java bean之间的映射。在默认情况下，MapStruct会智能地处理源对象中的null值：如果源字段为null，则对应的目标字段通常不会被设置（除非有特殊配置）。然而，当开发者希望在源字段非空时，将目标字段设置为一个预定义的常量值，而不是源字段本身的值时，情况会变得复杂。直接使用@Mapping(target = "targetField", constant = "CONSTANT_VALUE")会导致无论源字段是否为null，目标字段都会被设置为该常量，这与我们的需求不符。
为了实现“仅当源字段非空时，才将目标字段设置为常量”这一条件映射逻辑，MapStruct提供了多种灵活的扩展机制。下面将详细介绍两种主要的方法。
方法一：使用@QualifiedByName结合自定义方法
这种方法通过定义一个辅助方法来封装条件逻辑，并使用@QualifiedByName将其引用到映射配置中。这提供了一种集中管理和高度可重用的解决方案。
1. 定义辅助方法
首先，在一个工具类或映射器接口的伴生类中定义一个静态方法，该方法接收源字段的值作为参数，并根据条件返回常量或null。
public class CustomMapperQualifiers {
public static final String SET_CONSTANT_IF_NOT_NULL = "setConstantIfNotNull";
public static final String MY_CONSTANT_VALUE = "DEFAULT_VALUE_IF_NOT_NULL";
@Named(SET_CONSTANT_IF_NOT_NULL)
public static String mapTargetField(String sourceField) {
if (sourceField != null) {
return MY_CONSTANT_VALUE;
}
return null;
}
// 针对其他类型，可以重载或定义类似方法
@Named(SET_CONSTANT_IF_NOT_NULL)
public static Integer mapTargetField(Integer sourceField) {
if (sourceField != null) {
return 999; // 另一个常量
}
return null;
}
}在上述示例中，@Named注解为该方法提供了一个唯一的名称，供@QualifiedByName引用。
2. 在Mapper接口中使用
在你的MapStruct映射器接口中，通过@Mapping注解的qualifiedByName属性引用上述定义的辅助方法。
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.factory.Mappers;
@Mapper(uses = CustomMapperQualifiers.class) // 引入辅助类
public interface MyMapper {
MyMapper INSTANCE = Mappers.getMapper(MyMapper.class);
@Mapping(target = "targetField", source = "sourceField", qualifiedByName = CustomMapperQualifiers.SET_CONSTANT_IF_NOT_NULL)
TargetObject sourceToTarget(SourceObject source);
}优点：
- 集中管理与重用： 条件逻辑被封装在一个独立的方法中，可以在多个映射器或多个字段中重用。
- 易于重构： 当常量值或条件逻辑需要改变时，只需修改辅助方法，而无需遍历所有使用该逻辑的@Mapping注解。
- 类型安全： 辅助方法可以定义具体的输入和输出类型，编译时检查更严格。
- 代码清晰： 映射器接口保持简洁，业务逻辑在辅助方法中实现。
缺点：
- 需要额外的辅助方法和@Named注解，对于非常简单的单次使用场景可能显得有些繁琐。
方法二：使用@Expression和三元运算符
@Expression注解允许你在映射配置中直接嵌入Java表达式。结合三元运算符，可以实现简洁的条件逻辑。
1. 在Mapper接口中使用
直接在@Mapping注解的expression属性中编写Java三元运算符表达式。
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.factory.Mappers;
@Mapper
public interface MyMapper {
MyMapper INSTANCE = Mappers.getMapper(MyMapper.class);
// 定义一个常量，或者直接在表达式中使用字符串字面量
String MY_CONSTANT_VALUE = "DEFAULT_VALUE_IF_NOT_NULL";
@Mapping(target = "targetField", expression = "java(source.getSourceField() == null ? null : MyMapper.MY_CONSTANT_VALUE)")
TargetObject sourceToTarget(SourceObject source);
}在表达式java(source.getSourceField() == null ? null : MyMapper.MY_CONSTANT_VALUE)中：
- source代表源对象实例。
- source.getSourceField()获取源字段的值。
- 三元运算符? :根据源字段是否为null来决定返回null还是预设的常量。
优点：
- 简洁明了： 对于单个字段的简单条件，代码非常紧凑，无需额外的辅助方法。
- 内联逻辑： 逻辑直接嵌入映射配置中，一目了然。
缺点：
- 难以重构： 如果字段名称或常量值发生变化，需要手动修改所有相关的@Mapping表达式。
- 可读性下降： 当表达式变得复杂时，可读性和维护性会降低。
- 重复代码： 如果多个字段需要相同的条件逻辑，会导致表达式重复。
- 类型安全较低： 表达式是字符串，编译时不会对其中的方法调用或字段访问进行严格检查，可能导致运行时错误。
两种方法的比较与选择
| 特性 | @QualifiedByName + 自定义方法 | @Expression + 三元运算符 |
|---|---|---|
| 代码复用 | 高，逻辑集中，易于多处引用。 | 低，逻辑分散在每个@Mapping中，易产生重复。 |
| 重构难度 | 低，修改辅助方法即可影响所有引用处。 | 高，需手动查找并修改所有相关的表达式。 |
| 可读性 | 映射器接口简洁，业务逻辑在辅助方法中清晰定义。 | 对于简单逻辑很直观，复杂逻辑会降低可读性。 |
| 类型安全 | 高，辅助方法有明确的输入输出类型，编译时检查。 | 低，表达式为字符串，编译时检查有限，可能导致运行时错误。 |
| 适用场景 | 适用于通用、复杂或需要在多个字段/映射器中重用的条件逻辑。 | 适用于单个字段、简单且不常变动的条件逻辑。 |
| 代码量 | 略多，需要额外定义辅助方法。 | 略少，直接在@Mapping中实现。 |
总结与建议
在选择这两种方法时，应根据项目的具体需求和复杂性进行权衡：
- 对于单个、不常变动的字段，且条件逻辑非常简单的情况，@Expression提供了一种简洁的解决方案。 它的优势在于直接和内联，避免了额外的代码文件。
- 对于需要将相同条件逻辑应用于多个字段，或者逻辑本身较为复杂，以及未来可能需要重构和维护的场景，强烈推荐使用@QualifiedByName结合自定义方法。 这种方法通过集中管理业务逻辑，显著提高了代码的可维护性、可重用性和类型安全性。
在实际开发中，优先考虑代码的可读性、可维护性和长期稳定性。尽管@Expression在某些情况下看起来更简洁，但其在重构和类型安全方面的劣势往往会在项目后期带来更高的维护成本。因此，对于任何非一次性的通用条件映射需求，@QualifiedByName通常是更稳健的选择。
