Java中MapStruct转换实体的步骤实现

<!-- 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>
​
<!-- 若用 Lombok，需确保 MapStruct 能识别 Lombok 生成的 getter/setter -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.30</version>
    <scope>provided</scope>
</dependency>
​
<!-- Lombok 与 MapStruct 兼容依赖（Java 11+ 可能需要） -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok-mapstruct-binding</artifactId>
    <version>0.2.0</version>
    <scope>provided</scope>
</dependency>

// 数据库实体（POJO）
@Data
@NoArgsConstructor
@AllArgsConstructor
public class UserEntity {
    private Long id;          // 主键
    private String userName;  // 用户名（字段名：userName）
    private Integer age;      // 年龄（int 类型）
    private LocalDate birth;  // 生日（LocalDate 类型）
    private String phone;     // 手机号
}
​
// 前端传输对象（DTO）
@Data
@NoArgsConstructor
@AllArgsConstructor
public class UserDTO {
    private Long userId;      // 主键（字段名：userId，与实体 id 对应）
    private String name;      // 用户名（字段名：name，与实体 userName 对应）
    private String age;       // 年龄（String 类型，与实体 int 对应）
    private String birth;     // 生日（String 类型，格式：yyyy-MM-dd）
    private String phoneNum;  // 手机号（字段名：phoneNum，与实体 phone 对应）
}

import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.Mappings;
import org.mapstruct.factory.Mappers;
​
// 关键注解：componentModel="spring" → Spring 管理该映射器
@Mapper(componentModel = "spring", imports = {LocalDate.class, DateTimeFormatter.class})
public interface UserConvert {
​
    // 方式 1：Spring 依赖注入用（无需手动创建实例）
    // 方式 2：非 Spring 环境用（手动获取实例）
    // UserConvert INSTANCE = Mappers.getMapper(UserConvert.class);
​
    /**
     * DTO → 实体（核心映射方法）
     * @Mapping：指定字段映射规则（字段名不一致、类型转换、格式转换）
     */
    @Mappings({
        // DTO 的 userId → 实体的 id（字段名不一致）
        @Mapping(source = "userId", target = "id"),
        // DTO 的 name → 实体的 userName（字段名不一致）
        @Mapping(source = "name", target = "userName"),
        // DTO 的 age（String）→ 实体的 age（int）：自动类型转换（MapStruct 内置支持）
        @Mapping(source = "age", target = "age"),
        // DTO 的 birth（String）→ 实体的 birth（LocalDate）：自定义格式转换
        @Mapping(
            source = "birth",
            target = "birth",
            dateFormat = "yyyy-MM-dd" // 指定日期格式
        ),
        // DTO 的 phoneNum → 实体的 phone（字段名不一致）
        @Mapping(source = "phoneNum", target = "phone")
    })
    UserEntity dtoToEntity(UserDTO userDTO);
​
    /**
     * 实体 → DTO（反向映射，字段名对应规则与正向一致）
     * 可复用正向映射规则，用 @InheritInverseConfiguration 简化
     */
    @InheritInverseConfiguration(name = "dtoToEntity")
    @Mapping(
        source = "birth",
        target = "birth",
        dateFormat = "yyyy-MM-dd" // 反向转换也需指定日期格式
    )
    UserDTO entityToDto(UserEntity userEntity);
​
    /**
     * 自定义转换逻辑（如特殊格式处理、复杂计算）
     * 若 MapStruct 内置转换不满足，可定义默认方法（default）
     */
    default Integer stringToAge(String ageStr) {
        if (ageStr == null || ageStr.trim().isEmpty()) {
            return 0; // 空值默认 0
        }
        try {
            return Integer.parseInt(ageStr.trim());
        } catch (NumberFormatException e) {
            return 0; // 格式错误默认 0
        }
    }
​
    // 反向转换：Integer → String
    default String ageToString(Integer age) {
        return age == null ? "" : String.valueOf(age);
    }
}

// 自动生成的实现类（Spring 管理）
@Component
public class UserConvertImpl implements UserConvert {
​
    @Override
    public UserEntity dtoToEntity(UserDTO userDTO) {
        if (userDTO == null) {
            return null;
        }
        UserEntity userEntity = new UserEntity();
        userEntity.setId(userDTO.getUserId());
        userEntity.setUserName(userDTO.getName());
        // 调用自定义的 stringToAge 方法转换类型
        userEntity.setAge(stringToAge(userDTO.getAge()));
        // 自动按指定格式转换 String → LocalDate
        if (userDTO.getBirth() != null) {
            userEntity.setBirth(LocalDate.parse(userDTO.getBirth(), DateTimeFormatter.ofPattern("yyyy-MM-dd")));
        }
        userEntity.setPhone(userDTO.getPhoneNum());
        return userEntity;
    }
​
    @Override
    public UserDTO entityToDto(UserEntity userEntity) {
        // 类似正向转换逻辑，自动处理字段映射和类型转换
    }
​
    // 自动生成自定义方法的调用逻辑...
}

@Service
public class UserService {
​
    @Autowired
    private UserConvert userConvert; // 注入 MapStruct 映射器
​
    public void addUser(UserDTO userDTO) {
        // 1. DTO → 实体（自动完成字段映射和类型转换）
        UserEntity userEntity = userConvert.dtoToEntity(userDTO);
        
        // 2. 存入数据库（假设用 MyBatis 操作）
        // userMapper.insert(userEntity);
        
        System.out.println("转换后的实体：" + userEntity);
    }
​
    public UserDTO getUserById(Long id) {
        // 1. 从数据库查询实体
        UserEntity userEntity = new UserEntity(id, "张三", 25, LocalDate.of(2000, 1, 1), "13800138000");
        
        // 2. 实体 → DTO（反向转换）
        UserDTO userDTO = userConvert.entityToDto(userEntity);
        
        return userDTO;
    }
}

// 测试 DTO → 实体
UserDTO dto = new UserDTO(1L, "张三", "25", "2000-01-01", "13800138000");
UserEntity entity = userConvert.dtoToEntity(dto);
// 输出：UserEntity(id=1, userName=张三, age=25, birth=2000-01-01, phone=13800138000)
​
// 测试实体 → DTO
UserEntity entity = new UserEntity(1L, "张三", 25, LocalDate.of(2000, 1, 1), "13800138000");
UserDTO dto = userConvert.entityToDto(entity);
// 输出：UserDTO(userId=1, name=张三, age=25, birth=2000-01-01, phoneNum=13800138000)

@Mapper(componentModel = "spring")
public interface UserConvert {
    // 单个对象映射（已定义）
    UserEntity dtoToEntity(UserDTO dto);
    UserDTO entityToDto(UserEntity entity);
​
    // 集合映射（自动生成，无需手动写实现）
    List<UserEntity> dtoListToEntityList(List<UserDTO> dtoList);
    Set<UserDTO> entitySetToDtoSet(Set<UserEntity> entitySet);
}

// 示例：枚举转换
public enum GenderEnum {
    MALE(1, "男"), FEMALE(2, "女");
    // getter/setter/静态方法...
}
​
// DTO 中 gender 是 String 类型（"男"/"女"），实体中是 GenderEnum
@Mapping(
    source = "gender",
    target = "gender",
    qualifiedByName = "genderStrToEnum" // 指定自定义转换方法
)
UserEntity dtoToEntity(UserDTO dto);
​
// 自定义枚举转换方法（用 @Named 标识）
@Named("genderStrToEnum")
default GenderEnum genderStrToEnum(String genderStr) {
    if ("男".equals(genderStr)) return GenderEnum.MALE;
    if ("女".equals(genderStr)) return GenderEnum.FEMALE;
    return null;
}

@Mapper(componentModel = "spring")
public interface UserConvert {
​
    @Autowired
    UserService userService; // 注入 Spring 服务
​
    @Mapping(
        source = "userId",
        target = "deptId",
        qualifiedByName = "getDeptIdByUserId" // 调用注入的服务
    )
    UserEntity dtoToEntity(UserDTO dto);
​
    @Named("getDeptIdByUserId")
    default Long getDeptIdByUserId(Long userId) {
        // 调用业务服务获取部门ID（复杂逻辑）
        return userService.getDeptIdByUserId(userId);
    }
}

// 日期格式
@Mapping(source = "birth", target = "birth", dateFormat = "yyyy-MM-dd HH:mm:ss")
// 数字格式（如保留2位小数）
@Mapping(source = "amount", target = "amount", numberFormat = "#.00")
UserEntity dtoToEntity(UserDTO dto);