<!-- MapStruct 核心依賴(lài) -->
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct</artifactId>
    <version>1.5.5.Final</version> <!-- 推薦穩(wěn)定版 -->
</dependency>
?
<!-- 編譯期代碼生成依賴(lài)（必須，否則不會(huì)生成實(shí)現(xiàn)類(lèi)） -->
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct-processor</artifactId>
    <version>1.5.5.Final</version>
    <scope>provided</scope>
</dependency>
?
<!-- 若用 Lombok，需確保 MapStruct 能識(shí)別 Lombok 生成的 getter/setter -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.30</version>
    <scope>provided</scope>
</dependency>
?
<!-- Lombok 與 MapStruct 兼容依賴(lài)（Java 11+ 可能需要） -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok-mapstruct-binding</artifactId>
    <version>0.2.0</version>
    <scope>provided</scope>
</dependency>

// 數(shù)據(jù)庫(kù)實(shí)體（POJO）
@Data
@NoArgsConstructor
@AllArgsConstructor
public class UserEntity {
    private Long id;          // 主鍵
    private String userName;  // 用戶(hù)名（字段名：userName）
    private Integer age;      // 年齡（int 類(lèi)型）
    private LocalDate birth;  // 生日（LocalDate 類(lèi)型）
    private String phone;     // 手機(jī)號(hào)
}
?
// 前端傳輸對(duì)象（DTO）
@Data
@NoArgsConstructor
@AllArgsConstructor
public class UserDTO {
    private Long userId;      // 主鍵（字段名：userId，與實(shí)體 id 對(duì)應(yīng)）
    private String name;      // 用戶(hù)名（字段名：name，與實(shí)體 userName 對(duì)應(yīng)）
    private String age;       // 年齡（String 類(lèi)型，與實(shí)體 int 對(duì)應(yīng)）
    private String birth;     // 生日（String 類(lèi)型，格式：yyyy-MM-dd）
    private String phoneNum;  // 手機(jī)號(hào)（字段名：phoneNum，與實(shí)體 phone 對(duì)應(yīng)）
}

import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.Mappings;
import org.mapstruct.factory.Mappers;
?
// 關(guān)鍵注解：componentModel="spring" → Spring 管理該映射器
@Mapper(componentModel = "spring", imports = {LocalDate.class, DateTimeFormatter.class})
public interface UserConvert {
?
    // 方式 1：Spring 依賴(lài)注入用（無(wú)需手動(dòng)創(chuàng)建實(shí)例）
    // 方式 2：非 Spring 環(huán)境用（手動(dòng)獲取實(shí)例）
    // UserConvert INSTANCE = Mappers.getMapper(UserConvert.class);
?
    /**
     * DTO → 實(shí)體（核心映射方法）
     * @Mapping：指定字段映射規(guī)則（字段名不一致、類(lèi)型轉(zhuǎn)換、格式轉(zhuǎn)換）
     */
    @Mappings({
        // DTO 的 userId → 實(shí)體的 id（字段名不一致）
        @Mapping(source = "userId", target = "id"),
        // DTO 的 name → 實(shí)體的 userName（字段名不一致）
        @Mapping(source = "name", target = "userName"),
        // DTO 的 age（String）→ 實(shí)體的 age（int）：自動(dòng)類(lèi)型轉(zhuǎn)換（MapStruct 內(nèi)置支持）
        @Mapping(source = "age", target = "age"),
        // DTO 的 birth（String）→ 實(shí)體的 birth（LocalDate）：自定義格式轉(zhuǎn)換
        @Mapping(
            source = "birth",
            target = "birth",
            dateFormat = "yyyy-MM-dd" // 指定日期格式
        ),
        // DTO 的 phoneNum → 實(shí)體的 phone（字段名不一致）
        @Mapping(source = "phoneNum", target = "phone")
    })
    UserEntity dtoToEntity(UserDTO userDTO);
?
    /**
     * 實(shí)體 → DTO（反向映射，字段名對(duì)應(yīng)規(guī)則與正向一致）
     * 可復(fù)用正向映射規(guī)則，用 @InheritInverseConfiguration 簡(jiǎn)化
     */
    @InheritInverseConfiguration(name = "dtoToEntity")
    @Mapping(
        source = "birth",
        target = "birth",
        dateFormat = "yyyy-MM-dd" // 反向轉(zhuǎn)換也需指定日期格式
    )
    UserDTO entityToDto(UserEntity userEntity);
?
    /**
     * 自定義轉(zhuǎn)換邏輯（如特殊格式處理、復(fù)雜計(jì)算）
     * 若 MapStruct 內(nèi)置轉(zhuǎn)換不滿(mǎn)足，可定義默認(rèn)方法（default）
     */
    default Integer stringToAge(String ageStr) {
        if (ageStr == null || ageStr.trim().isEmpty()) {
            return 0; // 空值默認(rèn) 0
        }
        try {
            return Integer.parseInt(ageStr.trim());
        } catch (NumberFormatException e) {
            return 0; // 格式錯(cuò)誤默認(rèn) 0
        }
    }
?
    // 反向轉(zhuǎn)換：Integer → String
    default String ageToString(Integer age) {
        return age == null ? "" : String.valueOf(age);
    }
}

// 自動(dòng)生成的實(shí)現(xiàn)類(lèi)（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());
        // 調(diào)用自定義的 stringToAge 方法轉(zhuǎn)換類(lèi)型
        userEntity.setAge(stringToAge(userDTO.getAge()));
        // 自動(dòng)按指定格式轉(zhuǎn)換 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) {
        // 類(lèi)似正向轉(zhuǎn)換邏輯，自動(dòng)處理字段映射和類(lèi)型轉(zhuǎn)換
    }
?
    // 自動(dòng)生成自定義方法的調(diào)用邏輯...
}

@Service
public class UserService {
?
    @Autowired
    private UserConvert userConvert; // 注入 MapStruct 映射器
?
    public void addUser(UserDTO userDTO) {
        // 1. DTO → 實(shí)體（自動(dòng)完成字段映射和類(lèi)型轉(zhuǎn)換）
        UserEntity userEntity = userConvert.dtoToEntity(userDTO);
        
        // 2. 存入數(shù)據(jù)庫(kù)（假設(shè)用 MyBatis 操作）
        // userMapper.insert(userEntity);
        
        System.out.println("轉(zhuǎn)換后的實(shí)體：" + userEntity);
    }
?
    public UserDTO getUserById(Long id) {
        // 1. 從數(shù)據(jù)庫(kù)查詢(xún)實(shí)體
        UserEntity userEntity = new UserEntity(id, "張三", 25, LocalDate.of(2000, 1, 1), "13800138000");
        
        // 2. 實(shí)體 → DTO（反向轉(zhuǎn)換）
        UserDTO userDTO = userConvert.entityToDto(userEntity);
        
        return userDTO;
    }
}

// 測(cè)試 DTO → 實(shí)體
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)
?
// 測(cè)試實(shí)體 → 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 {
    // 單個(gè)對(duì)象映射（已定義）
    UserEntity dtoToEntity(UserDTO dto);
    UserDTO entityToDto(UserEntity entity);
?
    // 集合映射（自動(dòng)生成，無(wú)需手動(dòng)寫(xiě)實(shí)現(xiàn)）
    List<UserEntity> dtoListToEntityList(List<UserDTO> dtoList);
    Set<UserDTO> entitySetToDtoSet(Set<UserEntity> entitySet);
}

// 示例：枚舉轉(zhuǎn)換
public enum GenderEnum {
    MALE(1, "男"), FEMALE(2, "女");
    // getter/setter/靜態(tài)方法...
}
?
// DTO 中 gender 是 String 類(lèi)型（"男"/"女"），實(shí)體中是 GenderEnum
@Mapping(
    source = "gender",
    target = "gender",
    qualifiedByName = "genderStrToEnum" // 指定自定義轉(zhuǎn)換方法
)
UserEntity dtoToEntity(UserDTO dto);
?
// 自定義枚舉轉(zhuǎn)換方法（用 @Named 標(biāo)識(shí)）
@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 服務(wù)
?
    @Mapping(
        source = "userId",
        target = "deptId",
        qualifiedByName = "getDeptIdByUserId" // 調(diào)用注入的服務(wù)
    )
    UserEntity dtoToEntity(UserDTO dto);
?
    @Named("getDeptIdByUserId")
    default Long getDeptIdByUserId(Long userId) {
        // 調(diào)用業(yè)務(wù)服務(wù)獲取部門(mén)ID（復(fù)雜邏輯）
        return userService.getDeptIdByUserId(userId);
    }
}

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