当使用 MapStruct 将普通 Java 类映射到 record 类型时，若 record 字段为泛型集合（如 List），编译器会错误地将字段名（如 stringList）截断为 ingList，导致“Unmapped target property”编译错误。根本原因在于 MapStruct 对 record 的属性推导机制与传统 bean 不兼容。
当使用 mapstruct 将普通 java 类映射到 record 类型时，若 record 字段为泛型集合（如 `list
MapStruct 在 1.5.x 及更早版本中默认采用「getter/setter 命名解析」策略推导属性名：它扫描目标类型的所有 getter 方法（如 getStringList()），然后机械地移除前缀 get（3 字符）并执行首字母小写，得到 stringList。但 Java record 并不生成标准 getter 方法——其 stringList() 是一个无前缀的直接访问方法。MapStruct 错误地将其识别为 getStringList() 的变体，进而移除 get 后剩余 ringList，再因大小写转换逻辑异常进一步错判为 ingList，最终导致映射失败。
该问题并非仅限于 List
✅ 推荐解决方案
方案一：为 record 显式添加标准 getter（最轻量、推荐）
在 record 中补充符合 JavaBean 规范的 getter 方法，引导 MapStruct 正确识别属性：
public record ClassB(
String someString,
List<String> stringList
) {
// 显式提供标准 getter，覆盖默认方法签名
public List<String> getStringList() {
return stringList;
}
}✅ 优势：无需修改 Mapper 接口，零运行时开销，兼容所有 MapStruct 版本（≥1.4.2）。
⚠️ 注意：确保方法返回类型与字段类型严格一致（含泛型），否则 MapStruct 可能忽略该 getter。
方案二：使用 @Mapping 显式声明映射关系
在 Mapper 接口中为问题字段添加精确映射配置：
@Mapper
public interface ABMapper {
ClassA bToA(ClassB classB);
@Mapping(target = "stringList", source = "stringList")
ClassB aToB(ClassA classA);
}✅ 优势：不侵入 domain 层，适合无法修改 record 定义的场景。
⚠️ 注意：需为每个泛型集合字段单独配置；若字段较多，维护成本上升。
方案三：升级至 MapStruct 1.6.0+ 并启用 record 模式（前瞻性方案）
MapStruct 1.6.0 起引入了对 record 的原生支持（通过 @Mapper(record = true) 或全局配置）。启用后，工具将跳过 getter 解析，直接基于 record 构造函数参数推导属性名：
@Mapper(record = true)
public interface ABMapper {
ClassA bToA(ClassB classB);
ClassB aToB(ClassA classA);
}✅ 优势：彻底根治问题，语义清晰，未来兼容性强。
⚠️ 注意：需确认项目已升级至 MapStruct 1.6.0 或更高版本，并验证构建环境（如 Maven 插件、注解处理器）支持新特性。
? 验证与最佳实践
- 编译时开启 -Xlint:all 可捕获未映射字段警告，辅助定位类似问题；
- 避免在 record 中混用 private 字段与泛型集合——record 字段天然 final，应始终通过构造函数初始化；
- 单元测试中建议覆盖 aToB() 和 bToA() 双向映射，尤其验证集合内容是否深拷贝（MapStruct 默认浅拷贝，必要时配合 @DeepClone）。
综上，为 record 添加标准 getter 是当前最稳定、低侵入的修复方式；长期项目应规划升级至 MapStruct 1.6+ 并启用原生 record 支持，以获得更健壮的不可变类型映射能力。
