mapstruct中的@Mapper注解的基本用法_Java

在mapstruct中，@mapper注解是核心注解之一，用于标记一个接口或抽象类为mapstruct的映射器（mapper）。mapstruct会在编译时自动生成该接口的实现类，完成对象之间的属性映射。以下是对@mapper注解的详细解析：

1. 基本用法

@mapper注解可以单独使用，也可以配合其他属性进行配置。以下是一个简单的示例：

import org.mapstruct.mapper;
import org.mapstruct.mapping;
import org.mapstruct.factory.mappers;
@mapper
public interface usermapper {
    usermapper instance = mappers.getmapper(usermapper.class);
    @mapping(source = "username", target = "name")
    userdto touserdto(user user);
}

@mapper：标记接口为mapstruct的映射器。
mappers.getmapper(usermapper.class)：获取mapstruct自动生成的映射器实例。
@mapping：指定属性映射规则（例如将user的username属性映射到userdto的name属性）。

2. 常用属性

@mapper注解支持多种属性，用于配置映射器的行为：

(1) componentmodel

指定生成的映射器实现类的组件模型，便于与其他框架（如spring、cdi）集成。

可选值： default：默认模型，不依赖任何框架。

spring：生成的映射器实现类会带有@component注解，便于spring管理。
cdi：生成的映射器实现类会带有@applicationscoped注解，便于cdi管理。
jsr330：生成的映射器实现类会带有@javax.inject.named和@javax.inject.singleton注解。

示例：

@mapper(componentmodel = "spring")
public interface usermapper {
    usermapper instance = mappers.getmapper(usermapper.class);
    // ...
}

(2) uses

指定其他映射器或工具类，用于在映射过程中调用。

示例：

@mapper(uses = {datemapper.class})
public interface usermapper {
    usermapper instance = mappers.getmapper(usermapper.class);
    // ...
}

(3) implementationname 和 implementationpackage

implementationname：指定生成的映射器实现类的名称（默认为接口名+impl）。
implementationpackage：指定生成的映射器实现类的包名（默认为接口所在包）。

示例：

@mapper(implementationname = "customusermapperimpl", implementationpackage = "com.example.mappers")
public interface usermapper {
    // ...
}

(4) unmappedtargetpolicy

指定当目标对象有未映射的属性时的处理策略。

可选值：

error：抛出异常（默认值）。
warn：生成警告日志。
ignore：忽略未映射的属性。

示例：

@mapper(unmappedtargetpolicy = reportingpolicy.ignore)
public interface usermapper {
    // ...
}

(5) injectionstrategy

指定依赖注入的策略。

可选值：

field：通过字段注入（默认值）。
constructor：通过构造函数注入。
method：通过方法注入。

示例：

@mapper(componentmodel = "spring", injectionstrategy = injectionstrategy.constructor)
public interface usermapper {
    // ...
}

3. 高级用法

(1) 结合@mapperconfig

可以通过@mapperconfig定义全局配置，然后在@mapper中引用。

示例：

@mapperconfig(componentmodel = "spring", unmappedtargetpolicy = reportingpolicy.ignore)
public interface commonmapperconfig {
}
@mapper(config = commonmapperconfig.class)
public interface usermapper {
    // ...
}

(2) 自定义方法

可以在映射器接口中定义自定义方法，mapstruct会调用这些方法完成复杂的映射逻辑。

示例：

@mapper
public interface usermapper {
    usermapper instance = mappers.getmapper(usermapper.class);
    @mapping(target = "fullname", expression = "java(user.getfirstname() + \" \" + user.getlastname())")
    userdto touserdto(user user);
    default string formatdate(date date) {
        // 自定义日期格式化逻辑
        return new simpledateformat("yyyy-mm-dd").format(date);
    }
}

4. 注意事项

依赖配置：

确保项目中包含mapstruct的依赖和注解处理器（mapstruct和mapstruct-processor）。
如果使用lombok，确保lombok的版本兼容，并在构建工具（如maven或gradle）中正确配置。

映射规则：

如果源对象和目标对象的属性名相同，mapstruct会自动映射。
如果属性名不同，需要通过@mapping注解显式指定。

性能：

mapstruct生成的映射代码是类型安全的，且在编译时完成，性能优于运行时反射的映射工具（如apache commons beanutils）。

5. 总结

@mapper注解是mapstruct的核心，通过它可以：

定义映射器接口。
配置映射器的行为（如组件模型、未映射属性的处理策略等）。
结合其他注解（如@mapping）完成复杂的属性映射。
与其他框架（如spring）无缝集成。

通过合理使用@mapper注解及其属性，可以大大简化对象之间的映射逻辑，提高开发效率和代码质量。

6. 编译异常处理

针对mapstruct项目编译异常问题，可从依赖配置、ide设置、代码规范及版本兼容性四个维度进行排查和解决，以下是具体分析和建议：

现象：缺少必要的注解处理器依赖，如org.mapstruct:mapstruct-processor，导致编译时无法生成mapper类。
解决方案：
- maven项目：在pom.xml中添加mapstruct核心库和处理器依赖，例如：

<dependency>
    <groupid>org.mapstruct</groupid>
    <artifactid>mapstruct</artifactid>
    <version>1.5.3.final</version>
</dependency>
<dependency>
    <groupid>org.mapstruct</groupid>
    <artifactid>mapstruct-processor</artifactid>
    <version>1.5.3.final</version>
    <scope>provided</scope>
</dependency>

- **gradle项目**：在`build.gradle`中添加：

implementation 'org.mapstruct:mapstruct:1.5.3.final'
annotationprocessor 'org.mapstruct:mapstruct-processor:1.5.3.final'

ide设置问题

现象：ide未启用注解处理器或缓存异常，导致编译时无法正确处理mapstruct注解。
解决方案：
- intellij idea：打开“file”菜单，选择“settings”，导航至“build, execution, deployment” -> “compiler” -> “annotation processors”，勾选“enable annotation processing”选项，并清理ide缓存后重新构建项目。

代码规范问题

现象：mapper接口定义错误，如方法签名不匹配或缺少必要注解，导致编译失败。
解决方案：
- 验证mapper接口：确保接口符合mapstruct规范，例如：

@mapper
public interface usermapper {
    userdto usertouserdto(user user);
}

- **检查属性映射**：如果源对象和目标对象的属性名不同，需要通过`@mapping`注解显式指定，例如：

@mapper
public interface usermapper {
    @mapping(source = "username", target = "name")
    userdto usertouserdto(user user);
}

版本兼容性问题

现象：mapstruct版本与其他依赖（如lombok）不兼容，导致编译异常。
解决方案：
- 升级mapstruct版本：尝试升级至最新稳定版本，例如：

<dependency>
    <groupid>org.mapstruct</groupid>
    <artifactid>mapstruct</artifactid>
    <version>1.6.0.final</version>
</dependency>

- **解决lombok冲突**：如果项目中同时使用lombok和mapstruct，特别是使用lombok的`@builder`注解时，可能导致`@aftermapping`不生效。对于lombok版本1.18.16或更高版本，需添加`lombok-mapstruct-binding`依赖：

<dependency>
    <groupid>org.projectlombok</groupid>
    <artifactid>lombok-mapstruct-binding</artifactid>
    <version>0.2.0</version>
</dependency>

其他可能的问题及解决方案

未映射的目标属性：检查源对象和目标对象，确保存在对应的属性，或使用@mapping(target = "property", ignore = true)忽略不需要映射的属性。
枚举类型映射：自定义映射方法，例如：

@mapper
public interface enumconverter {
    default targetenum totargetenum(sourceenum sourceenum) {
        if (sourceenum == null) {
            return null;
        }
        switch (sourceenum) {
            case source_value1:
                return targetenum.target_value1;
            case source_value2:
                return targetenum.target_value2;
            default:
                throw new illegalargumentexception("unknown enum type: " + sourceenum);
        }
    }
}