如何用MapStruct实现特殊字段逻辑+默认空值忽略的PATCH映射？

我有如下DTO：

public class AccountDto {
  private Long id;
  private BigDecimal balance;
  private Currency currency;
}

及其对应的实体：

public class Account {

  @Id
  @Column(name = "id")
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  private Long id;

  @Column(name = "balance", scale = 2)
  private BigDecimal balance;

  @Column(name = "currency")
  @Enumerated(EnumType.STRING)
  private Currency currency;

  @Column(name = "created_at")
  @DateTimeFormat(iso = DateTimeFormat.ISO.DATE)
  @Builder.Default
  private Date createdAt = new Date();
  
  // 其他字段和方法
}

Currency是自定义枚举，包含约300种货币符号：

public enum Currency {
  AFN,
  EUR,
  ALL,
  DZD,
  USD,
  AOA,
  XCD,
  NUC,
  // 其他枚举值
}

我还有工具类CurrencyLedger，其方法convertAmountToTargetCurrency可实现货币金额转换。

希望用MapStruct实现从AccountDto到Account实体的PATCH映射逻辑：

• id和currency字段直接映射但空值时不覆盖实体值；
• balance字段需特殊处理：若DTO提供不同currency但未提供新balance，需调用转换方法调整实体原有余额。

最初通过抽象类注入CurrencyLedger并为每个字段加@Mapping注解，但字段过多时过于繁琐。尝试用@BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)替代，却出现编译错误提示未处理currency和id字段。

需要仅为balance字段定制逻辑，其余字段默认启用空值忽略映射，无需逐个添加@Mapping注解，请问该如何实现？

可以通过以下步骤实现需求，无需逐个配置字段映射：

1. 启用全局空值忽略策略
   在Mapper接口/抽象类上添加@BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)，全局设置所有字段默认忽略DTO中的空值，覆盖原有实体值的逻辑仅在DTO字段非空时触发。编译错误是因为MapStruct检测到balance字段存在联动逻辑，只需为该字段单独定制映射规则即可。

2. 定制balance字段的映射逻辑
   通过@Named注解标记自定义转换方法，再用@Mapping指定balance字段使用该方法。方法同时接收DTO和实体对象，能同时获取双方的字段值进行判断。

方式1：使用Mapper接口+默认方法 #

@Mapper(componentModel = "spring", uses = CurrencyLedger.class)
public interface AccountMapper {

    @BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
    @Mapping(target = "balance", qualifiedByName = "convertBalanceIfNeeded")
    void updateAccountFromDto(AccountDto dto, @MappingTarget Account entity);

    @Named("convertBalanceIfNeeded")
    default BigDecimal convertBalanceIfNeeded(AccountDto dto, Account entity, CurrencyLedger currencyLedger) {
        // 触发转换的条件：DTO指定了新货币、与实体原有货币不同、且未提供新余额
        if (dto.getCurrency() != null && !dto.getCurrency().equals(entity.getCurrency()) && dto.getBalance() == null) {
            return currencyLedger.convertAmountToTargetCurrency(entity.getBalance(), entity.getCurrency(), dto.getCurrency());
        }
        // 其他情况直接返回DTO的balance，空值会被全局策略忽略，保留实体原有值
        return dto.getBalance();
    }
}

方式2：使用抽象类注入工具类 #

@Mapper(componentModel = "spring")
public abstract class AccountMapper {

    @Autowired
    protected CurrencyLedger currencyLedger;

    @BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
    @Mapping(target = "balance", qualifiedByName = "convertBalanceIfNeeded")
    public abstract void updateAccountFromDto(AccountDto dto, @MappingTarget Account entity);

    @Named("convertBalanceIfNeeded")
    protected BigDecimal convertBalanceIfNeeded(AccountDto dto, Account entity) {
        if (dto.getCurrency() != null && !dto.getCurrency().equals(entity.getCurrency()) && dto.getBalance() == null) {
            return currencyLedger.convertAmountToTargetCurrency(entity.getBalance(), entity.getCurrency(), dto.getCurrency());
        }
        return dto.getBalance();
    }
}

3. 关键说明

• 全局空值策略会自动处理id、currency等所有字段的空值忽略，无需单独添加@Mapping注解；
• 自定义方法仅处理balance的特殊转换场景，其余场景直接返回DTO值，空值会被全局策略过滤；
• @MappingTarget用于指定要更新的目标实体对象，MapStruct会自动生成基于该对象的增量更新代码。

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