# mapstruct-convert

**Repository Path**: ColorDreams/mapstruct-convert

## Basic Information

- **Project Name**: mapstruct-convert
- **Description**: 一个基于MapStruct简单封装的Bean Convert/Copy工具包。
A Bean Convert/Copy toolkit based on simple encapsulation of MapStruct.

- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-05-18
- **Last Updated**: 2025-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

### 介绍

- 一个基于 [mapstruct](https://github.com/mapstruct/mapstruct) 简单封装的Bean Convert/Copy工具包。
- mapstruct 官方文档：[mapstruct](https://mapstruct.org/documentation/stable/reference/html/#Preface)

> 本类库没有对MapStruct进行任何修改，只是做了一层简单薄薄的封装以满足绝大部分的使用场景。
> 如需更多的 mapstruct 高阶用法可以查阅mapstruct官方文档。

### 使用指南

> 环境要求：JDK ≥ 17 || SpringBoot 3.X

1. 引入依赖

```xml
<!-- 原生使用 -->
<dependency>
    <groupId>io.gitee.colordreams</groupId>
    <artifactId>mapstruct-convert</artifactId>
    <version>3.0.0-RC1</version>
</dependency>

<!-- SpringBoot环境 -->
<dependency>
    <groupId>io.gitee.colordreams</groupId>
    <artifactId>mapstruct-convert-spring-boot-starter</artifactId>
    <version>3.0.0-RC1</version>
</dependency>
```

2. 配置
> 原生使用和SpringBoot环境使用已经做好了一些相应的功能实现，在maven编译插件中配置一下mapstruct-processor即可
```xml
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
                <source>17</source>
                <target>17</target>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>以你使用的mapstruct版本为准</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>
```
> 注意，如果你使用了`Lombok`，你还需要配置一下 `lombok-mapstruct-binding`
```xml
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
                <source>17</source>
                <target>17</target>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>以你使用的mapstruct版本为准</version>
                    </path>
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok-mapstruct-binding</artifactId>
                        <version>以你使用的lombok-mapstruct-binding版本为准</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>
```
3. 继承通用接口
> 假设有以下实体类
```java
public class User{
    private String username;
    private String password;
    /**
     * TODO copy该内容需要深拷贝
     */
    private List<BankCard> bankCards;

    /**
     * TODO DTO中不存在的字段会被自动忽略
     */
    private String phone;
    
    // 省略getter和setter
}

public class UserDTO{
    private String username;
    private String password;
    /**
     * TODO copy该内容需要深拷贝
     */
    private List<BankCard> bankCards;
    
    // 省略getter和setter
}

public class BankCard{
    private String cardNo;
    private String bankName;
    // 省略getter和setter
}
```
> 你需要实现一个这样的接口
```java
/**
 * 用户Bean转换
 */
@Mapper(mappingControl = DeepClone.class)
public interface UserMapper extends SourceTargetMapper<User, UserDTO>,BeanCopyMapper<User> {
    
}
```
> 上述代码中，`mappingControl = DeepClone.class`表示使用深克隆。
> 此外，如果你使用的是SpringBoot环境，还需要在代码中加入以下配置
```java
/**
 * 用户Bean转换
 */
@Mapper(componentModel = MappingConstants.ComponentModel.SPRING,mappingControl = DeepClone.class)
public interface UserMapper extends SourceTargetMapper<User, UserDTO>,BeanCopyMapper<User> {
    
}
```
> 其中 `MappingConstants.ComponentModel.SPRING` 本质上是一个字符串常量，你也可以写成 `componentModel = "spring"`。
> 这行配置的意思是生成的 MapperImpl 中，自动帮我们添加上Spring IOC容器的 `@Component` 注解，让Mapper自动注册到IOC容器中。

4. 使用
> 你可以使用类库提供的 BeanConvertUtil 工具类进行对象转换，它内部已经调用了 MapperFactory ，无需再做其它配置。
> 当然，如果你希望使用自己的 MapperFactory ，可以使用 `setMapperFactory` 方法进行替换，也可以继承该工具类扩展更多的方法。


```java
// 1、转换
User user = new User();
// user赋值操作...
UserDTO userDTO = BeanConvertUtil.toTarget(UserMapper.class,user);

// 2、反转
UserDTO userDTO = new UserDTO();
// userDTO赋值操作...
User user = BeanConvertUtil.toSource(UserMapper.class,userDTO);

// 3、拷贝
User userCopy = BeanConvertUtil.copy(UserMapper.class,user);

// 3、List转换与反转
// 和1、2的使用方法一样，只不过入参和出参是一个列表
List<UserDTO> dtoResults = BeanConvertUtil.toTargetList(UserMapper.class,userList);
List<User> userResults = BeanConvertUtil.toSourceList(UserMapper.class,UserDtoList);
// 除此之外，List转换和反转还提供了一个消费回调函数，每一个子项调用完成之后都会进行回调，方便进行一些值的处理
List<UserDTO> dtoResults = BeanConvertUtil.toTargetList(UserMapper.class,userList,userDto ->{
    // 进行处理操作
});
```

5. 关于Bean与Map转换
> 本类库没有对MapStruct进行任何修改与针对Map进行特殊处理，建议参阅[MapStruct官方文档 Map映射](https://mapstruct.org/documentation/stable/reference/html/#mapping-maps)