当使用 MapStruct 对含继承结构的抽象源类与目标类进行映射时，直接在主 Mapper 接口上为抽象父类字段（如 name）配置 @Mapping 会导致编译错误；需通过 @MapperConfig 定义通用映射规则，并结合 @InheritConfiguration 继承配置，方可安全、清晰地处理父类字段。
当使用 mapstruct 对含继承结构的抽象源类与目标类进行映射时，直接在主 mapper 接口上为抽象父类字段（如 `name`）配置 `@mapping` 会导致编译错误；需通过 `@mapperconfig` 定义通用映射规则，并结合 `@inheritconfiguration` 继承配置，方可安全、清晰地处理父类字段。
MapStruct 在处理多态映射（如 Vehicle → VehicleDto 及其子类）时，默认仅识别具体子类中声明的字段，而不会自动将 @Mapping 配置应用于抽象父类的构造器参数或 final 字段——尤其当目标类是抽象类且依赖构造器注入（如 VehicleDto(String name)）时，MapStruct 无法通过常规 setter 或字段赋值方式处理 name，导致 Unknown property "name" 编译错误。
根本原因在于：@Mapping(target = "name", ...) 要求目标类型存在可写入的 name 属性（如 setter 或可变字段），但 VehicleDto 中 name 是 final 字段，且仅通过构造器初始化。MapStruct 的 @SubclassMapping 机制会为每个子类生成独立的构造器调用（如 new CarDto(...)），但顶层抽象方法 mapToDto(Vehicle) 的 @Mapping 配置不会向下传递至子类构造逻辑中，因此被忽略。
✅ 正确解法是分离关注点：
- 使用
@MapperConfig定义通用、可复用的映射配置（支持对抽象基类字段的显式控制）； - 在配置方法中使用
@MappingTarget参数，使 MapStruct 执行“更新已有实例”而非“创建新实例”，从而绕过构造器限制，允许对final字段以外的场景（或配合 Lombok@Builder/@Wither等）灵活处理； - 主 Mapper 接口通过
@InheritConfiguration显式复用该配置，确保所有子类映射均继承父类字段逻辑。
以下是推荐实现：
@MapperConfig
public interface VehicleMapperConfig {
// 定义基础字段映射规则（支持 constant, expression, ignore 等）
@Mapping(target = "name", constant = "noname")
void mapVehicleToDto(Vehicle source, @MappingTarget VehicleDto target);
}
@Mapper(
config = VehicleMapperConfig.class,
subclassExhaustiveStrategy = SubclassExhaustiveStrategy.RUNTIME_EXCEPTION
)
public interface VehicleMapper {
@InheritConfiguration(name = "mapVehicleToDto") // ← 关键：继承配置
@SubclassMapping(target = CarDto.class, source = Car.class)
@SubclassMapping(target = MotorbikeDto.class, source = Motorbike.class)
VehicleDto mapToDto(Vehicle vehicle);
}
⚠️ 注意事项：
-
@MappingTarget方法必须为void，且第二个参数标注@MappingTarget，MapStruct 将生成“更新式”映射逻辑（要求目标类提供可写属性或 setter）；若目标类字段全为final且无 setter，则需改用 Builder 模式 +@Builder支持（需启用mapstruct.suppressGeneratorWarnings=true并配合@ObjectFactory）； -
@MapperConfig中的方法名（如mapVehicleToDto）需与@InheritConfiguration(name = "...")严格一致； - 若后续新增子类（如
Truck extends Vehicle），只需添加对应@SubclassMapping，无需修改配置接口——符合开闭原则； -
subclassExhaustiveStrategy = RUNTIME_EXCEPTION可在运行时捕获未覆盖的子类映射，增强健壮性。
此方案完全不侵入原有 Vehicle/VehicleDto 及其子类定义，符合“零修改源/目标类”的约束，是 MapStruct 处理抽象继承映射的官方推荐模式。
