MapStruct 在将普通 Java 类映射到 record 时，因错误解析泛型集合（如 List、Set）的 getter 名称，导致字段名被截去前三个字符（如 stringList → ingList），引发编译错误。本文详解根本原因并提供两种可靠、生产可用的修复方案。
mapstruct 在将普通 java 类映射到 record 时，因错误解析泛型集合（如 list、set）的 getter 名称，导致字段名被截去前三个字符（如 `stringlist` → `inglist`），引发编译错误。本文详解根本原因并提供两种可靠、生产可用的修复方案。
该问题并非配置疏漏或版本兼容性异常，而是 MapStruct 早期对 Java record 的支持存在设计局限：它沿用传统 JavaBean 的属性推导逻辑——通过反射查找 getXXX() 或 isXXX() 方法，并机械地移除前缀 get（3 字符）或 is（2 字符）来提取属性名。当目标类型为 record 且字段类型含泛型（如 List
✅ 推荐方案一：为 record 显式添加标准 getter（简洁、零侵入）
最直接的解决方式是在 record 中补充符合 JavaBean 规范的 getter 方法。MapStruct 将优先使用这些方法进行属性匹配，从而绕过错误的名称截断逻辑：
public record ClassB(
String someString,
List<String> stringList
) {
// 显式提供标准 getter，名称与字段完全一致
public List<String> getStringList() {
return stringList;
}
// 若需支持 null 安全，可添加空值处理（非必需）
public List<String> getStringListOrDefault() {
return Optional.ofNullable(stringList).orElse(List.of());
}
}✅ 优势：无需修改 Mapper 接口，不引入额外抽象类，完全兼容现有 MapStruct 配置；
⚠️ 注意：record 的 toString()、equals()、hashCode() 不受影响，getter 仅用于映射，语义清晰。
✅ 推荐方案二：使用抽象类自定义映射逻辑（灵活、可控）
当需精细控制转换逻辑（如深拷贝、空值策略、类型转换）时，可弃用接口式 Mapper，改用抽象类并手动实现：
@Mapper
public abstract class ABMapper {
// 手动实现 aToB：避免自动生成导致的截断错误
public ClassB aToB(ClassA classA) {
if (classA == null) return null;
return new ClassB(
classA.getSomeString(),
new ArrayList<>(Optional.ofNullable(classA.getStringList())
.orElse(Collections.emptyList()))
);
}
// bToA 可继续由 MapStruct 自动生成（无泛型字段截断风险）
public abstract ClassA bToA(ClassB classB);
}✅ 优势：彻底规避 MapStruct 的自动属性推导，100% 掌控转换行为；
⚠️ 注意：需确保 @Mapper 注解作用于抽象类，且 aToB 方法不可标注 @Mapping（否则仍触发生成逻辑）；泛型集合务必显式构造新实例（如 new ArrayList()），避免引用共享。
? 补充说明与最佳实践
- 版本建议：升级至 MapStruct 1.6.0+（当前最新稳定版为 1.6.2），官方已增强 record 支持，但该截断问题在部分泛型组合下仍可能复现，上述方案具有普适性；
- 避免反模式：不要尝试用 @Mapping(target = "stringList", source = "stringList") 强制指定——因字段名本身已被错误解析，此注解无效；
- 测试验证：务必编写单元测试覆盖 null 输入、空集合、含 null 元素等边界场景；
- 长期演进：关注 MapStruct GitHub Issue #2987（record 泛型字段映射优化），未来版本有望原生修复。
通过任一方案，即可稳定、高效地完成 ClassA 与 ClassB record 之间的双向映射，兼顾代码简洁性与运行时健壮性。
