在使用 MapStruct 进行对象映射时，难免会遇到各种各样的错误。这些错误可能会影响项目的正常运行，降低开发效率。因此，掌握 MapStruct 常见错误的排查方法至关重要。本节我们就来详细探讨如何快速定位并解决 MapStruct 使用中的常见问题。

常见错误场景列举

映射失败

映射失败是在使用 MapStruct 时经常遇到的问题之一。简单来说，就是 MapStruct 无法按照我们的预期将源对象的属性值正确地映射到目标对象上。

例如，假设我们有一个源对象 Source 和目标对象 Target，代码如下：

public class Source {
    private String name;
    // 省略 getter 和 setter 方法
}

public class Target {
    private String fullName;
    // 省略 getter 和 setter 方法
}

@Mapper
public interface SourceTargetMapper {
    Target sourceToTarget(Source source);
}

在这个例子中，由于源对象的 name 属性和目标对象的 fullName 属性名称不同，MapStruct 默认情况下可能无法正确映射，从而导致映射失败。

类型不匹配

类型不匹配也是一个常见的错误。当源对象的属性类型和目标对象对应属性的类型不一致时，就会出现类型不匹配的问题。

比如，源对象有一个 Integer 类型的属性，而目标对象对应属性是 String 类型。示例代码如下：

public class Source {
    private Integer age;
    // 省略 getter 和 setter 方法
}

public class Target {
    private String ageStr;
    // 省略 getter 和 setter 方法
}

@Mapper
public interface SourceTargetMapper {
    Target sourceToTarget(Source source);
}

这里，Source 类的 age 属性是 Integer 类型，而 Target 类的 ageStr 属性是 String 类型，MapStruct 默认不会自动进行类型转换，这就可能导致类型不匹配的错误。

方法未生成

有时候，我们定义了映射接口和方法，但在编译后发现对应的实现方法并没有生成。这可能是由于配置问题或者 MapStruct 插件没有正确工作导致的。

例如，在 Maven 项目中，如果没有正确配置 MapStruct 插件，就可能出现方法未生成的情况。以下是一个简单的 Maven 配置示例：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>1.4.2.Final</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

如果这个配置有问题，就可能导致 MapStruct 无法生成映射方法。

排查步骤

查看编译日志

当遇到问题时，首先要查看编译日志。编译日志中通常会包含详细的错误信息，这些信息可以帮助我们快速定位问题所在。

在 IDE 中，编译日志一般会显示在控制台窗口。例如，在 IntelliJ IDEA 中，我们可以在下方的 “Build” 窗口查看编译日志。如果出现映射失败或者类型不匹配的问题，日志中可能会提示找不到合适的映射方法或者类型转换错误等信息。

检查映射接口和方法定义

检查映射接口和方法的定义是否正确。确保接口上添加了 @Mapper 注解，并且方法的参数和返回值类型与源对象和目标对象的类型一致。

同时，要注意方法名和属性名的对应关系。如果属性名不一致，可能需要使用 @Mapping 注解来指定映射关系。例如，对于前面提到的 name 和 fullName 映射问题，可以这样修改：

@Mapper
public interface SourceTargetMapper {
    @Mapping(source = "name", target = "fullName")
    Target sourceToTarget(Source source);
}

检查依赖和配置

检查项目的依赖和配置是否正确。确保项目中添加了 MapStruct 的依赖，并且配置了正确的版本。

在 Maven 项目中，可以检查 pom.xml 文件中是否包含 MapStruct 的依赖：

<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct</artifactId>
    <version>1.4.2.Final</version>
</dependency>

同时，要确保编译插件的配置正确，能够正确生成映射方法。

解决方案

映射失败的解决方案

如果是由于属性名不一致导致的映射失败，可以使用 @Mapping 注解来指定映射关系。除了前面提到的示例，再看一个更复杂的例子：

public class Source {
    private String firstName;
    private String lastName;
    // 省略 getter 和 setter 方法
}

public class Target {
    private String fullName;
    // 省略 getter 和 setter 方法
}

@Mapper
public interface SourceTargetMapper {
    @Mapping(target = "fullName", expression = "java(source.getFirstName() + \" \" + source.getLastName())")
    Target sourceToTarget(Source source);
}

这里使用 expression 属性，通过 Java 表达式将 firstName 和 lastName 拼接成 fullName。

类型不匹配的解决方案

对于类型不匹配的问题，可以使用 @Mapping 注解的 qualifiedByName 或 qualifiedBy 属性来指定自定义的类型转换方法。

例如，对于 Integer 到 String 的类型转换，可以这样实现：

public class Source {
    private Integer age;
    // 省略 getter 和 setter 方法
}

public class Target {
    private String ageStr;
    // 省略 getter 和 setter 方法
}

@Mapper
public interface SourceTargetMapper {
    @Mapping(source = "age", target = "ageStr", qualifiedByName = "intToString")
    Target sourceToTarget(Source source);

    @Named("intToString")
    default String intToString(Integer value) {
        return value != null ? String.valueOf(value) : null;
    }
}

这里定义了一个名为 intToString 的方法，并使用 @Named 注解进行标记，然后在 @Mapping 注解中通过 qualifiedByName 属性引用该方法。

方法未生成的解决方案

如果方法未生成，首先要检查编译插件的配置是否正确。确保 maven-compiler-plugin 或 gradle-compiler-plugin 中配置了正确的 annotationProcessorPaths 或 annotationProcessor。

另外，要检查 IDE 是否正确配置了注解处理器。在 IntelliJ IDEA 中，可以在 “Settings” -> “Build, Execution, Deployment” -> “Compiler” -> “Annotation Processors” 中确保启用了注解处理器。

代码示例总结

以下是一个完整的代码示例，包含了前面提到的各种情况和解决方案：

import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.Named;

public class Source {
    private String firstName;
    private String lastName;
    private Integer age;

    public String getFirstName() {
        return firstName;
    }

    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

    public String getLastName() {
        return lastName;
    }

    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }
}

public class Target {
    private String fullName;
    private String ageStr;

    public String getFullName() {
        return fullName;
    }

    public void setFullName(String fullName) {
        this.fullName = fullName;
    }

    public String getAgeStr() {
        return ageStr;
    }

    public void setAgeStr(String ageStr) {
        this.ageStr = ageStr;
    }
}

@Mapper
public interface SourceTargetMapper {
    @Mapping(target = "fullName", expression = "java(source.getFirstName() + \" \" + source.getLastName())")
    @Mapping(source = "age", target = "ageStr", qualifiedByName = "intToString")
    Target sourceToTarget(Source source);

    @Named("intToString")
    default String intToString(Integer value) {
        return value != null ? String.valueOf(value) : null;
    }
}

public class Main {
    public static void main(String[] args) {
        Source source = new Source();
        source.setFirstName("John");
        source.setLastName("Doe");
        source.setAge(30);

        SourceTargetMapper mapper = org.mapstruct.factory.Mappers.getMapper(SourceTargetMapper.class);
        Target target = mapper.sourceToTarget(source);

        System.out.println("Full Name: " + target.getFullName());
        System.out.println("Age Str: " + target.getAgeStr());
    }
}

在这个示例中，我们通过 @Mapping 注解解决了属性名不一致和类型不匹配的问题，确保了 MapStruct 能够正确进行对象映射。

总结

通过本节的学习，我们了解了 MapStruct 常见的错误场景，如映射失败、类型不匹配和方法未生成等，并掌握了相应的排查步骤和解决方案。掌握这些内容后，你可以快速定位并解决 MapStruct 使用中的常见问题，提高项目的稳定性和开发效率。

下一节我们将深入学习 MapStruct 的性能优化策略，进一步完善对本章 MapStruct 性能优化与问题排查主题的认知。

---

🍃 MapStruct系列专栏导航

• 🔖 一站式掌握MapStruct：从基础到高级应用

建议按系列顺序阅读，从基础到进阶逐步掌握MapStruct核心能力，避免遗漏关键知识点～

系列文章衔接

• 🔖 《全面掌握Swagger：从入门到实战》
• 🍃 博客概览：《程序员技术成长导航，专栏汇总》