泛型字段映射至Java Record时字段名称被截断的编译错误问题

API 探路者

2026-8-1

MapStruct 泛型字段映射到 Java Record 时字段名被截断问题

问题描述

使用MapStruct做对象映射时，若源对象的字段是泛型类型（已测试List<>、Set<>，推测自定义泛型类型也会出现此问题），且映射目标为Java Record，会出现字段名称被错误截断的情况，直接导致编译失败。

编译报错信息（定位到aToB方法）：

Unmapped target property: "ingList"

能明显看到原字段stringList的前3个字符被截断，无法自动匹配Record的对应字段。

复现步骤

创建实体类ClassA：

public class ClassA {

    private String someString;
    private List<String> stringList;

    public String getSomeString() { return someString; }
    public void setSomeString(String someString) { this.someString = someString; }
    public List<String> getStringList() { return stringList; }
    public void setStringList(List<String> stringList) { this.stringList = stringList; }

}

创建Java Record类ClassB：

public record ClassB(
    String someString,
    List<String> stringList
) {};

定义MapStruct Mapper接口：

@Mapper
public interface ABMapper {
  ClassA bToA(ClassB classB);
  ClassB aToB(ClassA classA);
}

解决方案

显式指定映射关系
在对应的Mapper方法上添加@Mapping注解，手动绑定字段，强制MapStruct识别正确的字段名称：

@Mapper
public interface ABMapper {
  ClassA bToA(ClassB classB);

  @Mapping(source = "stringList", target = "stringList")
  ClassB aToB(ClassA classA);
}