MapStruct Java 完全指南：安装、方法与实战示例

什么是 MapStruct？为什么需要它？

MapStruct 是一个 Java 代码生成器，能够自动创建不同类型对象之间的映射器（转换器）实现。在现代 Java 开发中，经常需要将一个对象转换为另一个对象：Entity 转 DTO、DTO 转 VO、一个 API 响应转成另一种模型等等。手动编写这类代码既枯燥、耗时，又容易出错。MapStruct 通过在编译阶段生成所有样板代码，完美解决了这个问题。

MapStruct 的主要优势：

• 高性能：在编译时生成代码（compile-time）。不使用反射，运行时零性能损耗。MapStruct 的运行速度与手写映射代码一样快。
• 类型安全：所有错误（类型不匹配、字段缺失）都在编译时被发现，而不是在运行时。
• 简单易用：配置极少。只需定义一个包含映射方法的接口或抽象类，MapStruct 就会自动生成实现。
• 灵活强大：支持复杂映射、类型转换、表达式使用、方法调用，并能与其他库（Lombok、Spring 等）集成。
• 代码整洁：映射代码与业务逻辑分离，使代码更易读、更易维护。

MapStruct 在多层级架构（Controller-Service-Repository）中尤其有用，因为这种架构经常需要在各层之间转换对象。

安装 MapStruct

MapStruct 不是通过 pip 或 npm 安装的，因为它是一个 Java 库。要将其集成到项目中，需要使用 Maven 或 Gradle 构建系统。

通过 Maven 安装

在 pom.xml 文件中添加以下依赖：

<dependencies>
    <!-- MapStruct 核心库 -->
    <dependency>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct</artifactId>
        <version>1.5.5.Final</version>
    </dependency>

    <!-- 注解处理器（用于代码生成） -->
    <dependency>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct-processor</artifactId>
        <version>1.5.5.Final</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

通过 Gradle 安装

对于 Gradle，在 build.gradle 文件中添加：

dependencies {
    implementation 'org.mapstruct:mapstruct:1.5.5.Final'
    annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.5.Final'
}

重要提示：确保 mapstruct-processor 的版本与 mapstruct 的版本一致。添加依赖后，执行项目构建（例如 mvn clean compile），MapStruct 就会生成映射器的实现代码。

快速上手：代码示例

让我们创建一个简单的映射器，将 Car 对象（Entity）转换为 CarDto 对象（DTO）。

第一步：定义源类和目标类

// Car.java
public class Car {
    private String make;
    private int numberOfSeats;
    private CarType type;

    // 构造方法、getter、setter
    public Car() {}

    public Car(String make, int numberOfSeats, CarType type) {
        this.make = make;
        this.numberOfSeats = numberOfSeats;
        this.type = type;
    }

    public String getMake() { return make; }
    public void setMake(String make) { this.make = make; }
    public int getNumberOfSeats() { return numberOfSeats; }
    public void setNumberOfSeats(int numberOfSeats) { this.numberOfSeats = numberOfSeats; }
    public CarTy