BeanUtils.copyProperties(source, target);

@Mapper(componentModel = "spring")
public interface UserMapper {}

package com.example.demo.entity;

import lombok.Data;
import java.time.LocalDateTime;
// 创建到不同的类中
@Data
public class Address {
    private String street;
    private String city;
}

@Data
public class UserEntity {
    private Long id;
    private String username;
    private String password; 
    private String emailAddress; // 场景 1: 异名属性
    private Address address;     // 场景 2: 嵌套对象
    private Integer status;
    private LocalDateTime createTime;
}

package com.example.demo.vo;

import lombok.Data;

@Data
public class UserVO {
    private Long id;
    private String username;
    private String email;        // 目标字段名不同
    private String cityName;     // 目标需要扁平化提取 city
    private String statusDesc;   
    private String createTime;   
}

package com.example.demo.convert;

import com.example.demo.entity.UserEntity;
import com.example.demo.vo.UserVO;
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.Mappings;

// 1. 使用 org.mapstruct.Mapper，且指定交给 Spring 管理
@Mapper(componentModel = "spring")
public interface UserMapper {

    // 2. 核心映射配置
    @Mappings({
        // 场景 1：异名映射 (source -> target)
        @Mapping(source = "emailAddress", target = "email"),
        
        // 场景 2：点号导航 (Deep Mapping)
        // 直接提取 entity.getAddress().getCity() 赋值给 vo.cityName
        @Mapping(source = "address.city", target = "cityName")
    })
    UserVO toVO(UserEntity entity);
}

@Component // 1. 自动生成了 Spring 组件注解和编译信息注解
public class UserMapperImpl implements UserMapper {

    @Override
    public UserVO toVO(UserEntity entity) {
        if ( entity == null ) {
            return null; // 2. 自动处理顶层空指针，避免直接调用空对象方法
        }

        UserVO userVO = new UserVO();

        // 3. 异名属性映射：按照 Mapper 接口定义的规则，将 entity 的 emailAddress 映射到 VO 的 email
        userVO.setEmail( entity.getEmailAddress() );

        // 4. 嵌套对象多级空指针防御 (这一点 BeanUtils 很难做到)
        // MapStruct 自动生成独立工具方法，层层判空：先检查 entity 是否为空，再检查 address 是否为空，最后获取 city
        userVO.setCityName( entityAddressCity( entity ) );

        // 5. 同名属性自动映射：字段名、类型一致时，无需额外配置，自动完成赋值
        userVO.setId( entity.getId() );
        userVO.setUsername( entity.getUsername() );

        // 6. 日期类型格式化转换：将 LocalDateTime 类型自动格式化为 ISO 标准字符串，无需手动处理格式转换
        if ( entity.getCreateTime() != null ) {
            userVO.setCreateTime( DateTimeFormatter.ISO_LOCAL_DATE_TIME.format( entity.getCreateTime() ) );
        }

        return userVO;
    }

    // 自动生成的嵌套属性获取工具方法，包含完整的空指针检查逻辑
    private String entityAddressCity(UserEntity userEntity) {
        if ( userEntity == null ) {
            return null;
        }
        Address address = userEntity.getAddress();
        if ( address == null ) {
            return null;
        }
        String city = address.getCity();
        if ( city == null ) {
            return null;
        }
        return city;
    }
}

// 必选：标记接口，并纳入 Spring 容器管理
@Mapper(componentModel = "spring") 
public interface MyMapper { ... }

@Data
public class UserEntity {
    // ... 原有字段
    private String emailAddress; // 可能为 null
    private String traceId;      // 可能为 null
    private String source;       // 数据库中可能有旧值，但我们需要强制覆盖
}

@Data
public class UserVO {
    // ... 原有字段
    private String email;
    private String traceId;
    private String source; // 这是一个固定值字段
}

package com.example.demo.convert;

import com.example.demo.entity.UserEntity;
import com.example.demo.vo.UserVO;
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.Mappings;
import java.util.UUID; // 1. 导入需要使用的类

@Mapper(componentModel = "spring", imports = {UUID.class}) // 2. 注册导入
public interface UserMapper {

    @Mappings({
        // 策略 1 (defaultValue): 源 emailAddress 为空时，使用兜底值
        @Mapping(source = "emailAddress", target = "email", defaultValue = "no-email@example.com"),
        
        // 策略 2 (constant): 强制覆盖，不看 entity 中是否有 source
        @Mapping(target = "source", constant = "PC_BROWSER"),

        // 策略 3 (defaultExpression): traceId 为空时，调用 Java 代码生成
        // 注意：因为上面 imports 引入了 UUID，这里可以直接写 UUID.randomUUID()
        @Mapping(source = "traceId", target = "traceId", defaultExpression = "java(UUID.randomUUID().toString())"),
        
        // 保持之前的深度映射
        @Mapping(source = "address.city", target = "cityName")
    })
    UserVO toVO(UserEntity entity);
}

@Override
public UserVO toVO(UserEntity entity) {
    if ( entity == null ) {
        return null;
    }
    UserVO userVO = new UserVO();

    // 1. defaultValue 的实现：标准的判空分支
    if ( entity.getEmailAddress() != null ) {
        userVO.setEmail( entity.getEmailAddress() );
    }
    else {
        userVO.setEmail( "no-email@example.com" );
    }

    // 2. defaultExpression 的实现：嵌入了我们写的 Java 代码
    if ( entity.getTraceId() != null ) {
        userVO.setTraceId( entity.getTraceId() );
    }
    else {
        // 直接调用了 UUID.randomUUID()
        userVO.setTraceId( UUID.randomUUID().toString() );
    }

    // 3. constant 的实现：完全没有读取 entity.getSource()，直接赋值
    userVO.setSource( "PC_BROWSER" );

    // ... 其他逻辑
    return userVO;
}

@Mappings({
    // ... 前面的配置保持不变

    // 1. 日期格式化：LocalDateTime -> String
    @Mapping(source = "createTime", target 
             = "createTimeStr", dateFormat = "yyyy-MM-dd HH:mm:ss"),

    // 2. 数字格式化：BigDecimal -> String
    // 使用 DecimalFormat 模式：保留两位小数，不足补 0
    @Mapping(source = "balance", target = "balanceStr", numberFormat = "#0.00")
})
UserVO toVO(UserEntity entity);

// UserMapperImpl.java

// 1. 日期类型转换：LocalDateTime -> 格式化字符串（线程安全+自定义格式）
if ( entity.getCreateTime() != null ) {
    // 核心优势：使用 DateTimeFormatter（JDK8+ 推荐），相比 SimpleDateFormat 具备线程安全特性
    // 无需手动创建全局静态实例，MapStruct 自动生成局部格式化器，既安全又避免并发问题
    // 自定义格式 "yyyy-MM-dd HH:mm:ss"，满足业务场景下的日期展示需求（如页面显示、接口返回）
    userVO.setCreateTimeStr( DateTimeFormatter.ofPattern( "yyyy-MM-dd HH:mm:ss" )
        .format( entity.getCreateTime() ) );
}

// 2. 金额类型转换：数字类型（如 BigDecimal/Double）-> 格式化字符串（保留两位小数）
if ( entity.getBalance() != null ) { // 空值防御：避免对 null 金额执行格式化操作
    // 调用自定义工具方法创建 DecimalFormat，统一管理金额格式化规则
    // 格式 "#0.00" 表示：强制保留两位小数，整数部分无前置零（如 100.00、2.50、0.80）
    userVO.setBalanceStr( createDecimalFormat( "#0.00" ).format( entity.getBalance() ) );
}

/**
 * 金额格式化工具方法（MapStruct 自动生成，可复用）
 * 作用：统一配置 DecimalFormat 的核心参数，保证格式化逻辑一致性
 */
private DecimalFormat createDecimalFormat( String numberFormat ) {
    DecimalFormat df = new DecimalFormat( numberFormat ); // 传入自定义格式模板
    // 关键配置：设置解析时将数字解析为 BigDecimal 类型，避免浮点数精度丢失
    // 尤其适用于金额、汇率等对精度要求极高的场景
    df.setParseBigDecimal( true );
    return df;
}

// ... 正向 toVO 方法 ...

/**
 * 反向转换：VO -> Entity
 * 场景：用户修改个人信息
 */
// 1. 自动继承 toVO 的配置并反转 (如 email -> emailAddress)
// MapStruct 会自动反转逻辑：包括属性名的反转，以及 dateFormat 的反转 (String -> LocalDateTime)
@InheritInverseConfiguration(name = "toVO") 

// 2. 覆盖配置：在这里配置的属性，会覆盖掉“继承”来的逻辑
@Mappings({
    @Mapping(target = "id", ignore = true),         // 防止恶意修改 ID
    @Mapping(target = "password", ignore = true),   // 密码通过单独接口修改
    
    // 3. 覆盖 CreateTime：
    // 虽然 toVO 中配置了 dateFormat，但我们不希望前端修改创建时间，所以直接 ignore
    @Mapping(target = "createTime", ignore = true), 
    
    // 4. 特殊处理：前端传来的 source 是 "PC_BROWSER"，但数据库我们想存 "USER_SUBMIT"
    @Mapping(target = "source", constant = "USER_SUBMIT"),
})
UserEntity toEntity(UserVO vo);

package com.example.demo.controller;

import com.example.demo.convert.UserMapper;
import com.example.demo.entity.Address;
import com.example.demo.entity.UserEntity;
import com.example.demo.vo.UserVO;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;
import java.math.BigDecimal;
import java.time.LocalDateTime;

@RestController
@RequestMapping("/test/mapstruct")
@RequiredArgsConstructor // 使用构造器注入 UserMapper
public class MapStructTestController {

    private final UserMapper userMapper;

    /**
     * 验证：Entity -> VO
     * 测试点：空值兜底、格式化、常量注入
     */
    @GetMapping("/toVO")
    public UserVO testToVO() {
        // 1. 模拟一个 "脏" 数据：很多字段是 null
        UserEntity entity = new UserEntity();
        entity.setId(1001L);
        entity.setUsername("admin");
        entity.setCreateTime(LocalDateTime.now());
        entity.setBalance(new BigDecimal("1234.567")); // 测试精度截断
        // 注意：emailAddress, traceId, source 都是 null
        
        // 模拟嵌套对象
        Address addr = new Address();
        addr.setCity("Beijing");
        entity.setAddress(addr);

        return userMapper.toVO(entity);
    }

    /**
     * 验证：VO -> Entity
     * 测试点：反向映射、字段忽略
     */
    @PostMapping("/toEntity")
    public UserEntity testToEntity(@RequestBody UserVO vo) {
        // 模拟前端传入 VO，观察转换后的 Entity
        return userMapper.toEntity(vo);
    }
}

// 痛苦的回忆：手动循环
List<UserVO> voList = new ArrayList<>();
for (UserEntity entity : entityList) {
    UserVO vo = new UserVO();
    BeanUtils.copyProperties(entity, vo); // 还要处理异常
    voList.add(vo);
}
return voList;

@Mapper(componentModel = "spring", imports = {UUID.class})
public interface UserMapper {

    // 1. 单对象转换 (上一章已经写好)
    // MapStruct 会在生成集合转换时，自动调用这个方法处理每一个元素
    @Mappings({
        @Mapping(source = "emailAddress", target = "email", defaultValue = "no-email@example.com"),
        @Mapping(target = "source", constant = "PC_BROWSER"),
        // ... 其他配置保持不变
    })
    UserVO toVO(UserEntity entity);

    // 2. 新增：集合转换
    // 你不需要加任何 @Mapping 注解，框架会自动检测泛型 <UserEntity> -> <UserVO>
    // 并自动循环调用上面的 toVO 方法
    List<UserVO> toVOList(List<UserEntity> entityList);
}

@Override
public List<UserVO> toVOList(List<UserEntity> entityList) {
    // 1. 自动判空：如果入参 list 是 null，直接返回 null
    if ( entityList == null ) {
        return null;
    }

    // 2. 自动初始化目标集合，大小与源集合一致，避免扩容开销
    List<UserVO> list = new ArrayList<UserVO>( entityList.size() );
    
    // 3. 自动生成增强 for 循环
    for ( UserEntity userEntity : entityList ) {
        // 4. 循环调用单对象转换方法 toVO(userEntity)
        list.add( toVO( userEntity ) );
    }

    return list;
}

if ( entityList == null ) {
    return null; // 返回 null
}

import org.mapstruct.NullValueIterableMappingStrategy;

// 增加 nullValueIterableMappingStrategy 配置
@Mapper(
    componentModel = "spring", 
    imports = {UUID.class},
    nullValueIterableMappingStrategy = NullValueIterableMappingStrategy.RETURN_DEFAULT
)
public interface UserMapper {
    // ... 方法保持不变
}

@Override
public List<UserVO> toVOList(List<UserEntity> entityList) {
    if ( entityList == null ) {
        // 变化点：现在返回一个新的空 ArrayList，而不是 null
        return new ArrayList<UserVO>();
    }
    // ... 循环逻辑
}

/**
 * 场景一：Map <String, Date> -> Map <String, String>
 * 需求：Key 保持不变，Value 中的日期格式化为 yyyy-MM-dd
 */
@MapMapping(valueDateFormat = "yyyy-MM-dd")
Map<String, String> mapValueFormatting(Map<String, LocalDateTime> sourceMap);

@Override
public Map<String, String> mapValueFormatting(Map<String, LocalDateTime> sourceMap) {
    if ( sourceMap == null ) {
        return null;
    }
    // 2. 目标 Map 优化初始化：
    // - 采用 LinkedHashMap：保留源 Map 的键值对顺序（与 HashMap 相比，LinkedHashMap 维护插入顺序）
    // - 容量计算逻辑：Math.max( (int) (sourceMap.size() / .75f) + 1, 16 )
    //   原理：HashMap/LinkedHashMap 的负载因子默认是 0.75，当元素数量达到 容量*负载因子 时会触发扩容
    //   这里通过 sourceMap.size() / 0.75f + 1 计算出「刚好能容纳所有元素且不触发扩容」的最小容量
    //   再与 16（集合默认初始容量）取最大值，既避免扩容损耗，又保证最小初始容量的合理性
    Map<String, String> map = new LinkedHashMap<String, String>( Math.max( (int) ( sourceMap.size() / .75f ) + 1, 16 ) );

    // 3. 遍历源 Map 并执行 Value 转换：
    for ( java.util.Map.Entry<String, LocalDateTime> entry : sourceMap.entrySet() ) {
        String key = entry.getKey(); // 键直接复用，无需转换（类型一致）
        
        // 核心逻辑：LocalDateTime 类型 Value -> 格式化字符串
        // MapStruct 自动生成的格式化器实例（单例/复用设计）
        String value = dateTimeFormatter_yyyy_MM_dd_0159776256.format( entry.getValue() );
        
        map.put( key, value ); // 转换后的键值对放入目标 Map
    }

    return map; // 返回格式化后的目标 Map
}

// 错误示范：MapStruct 无法自动实现
UserEntity mapToEntity(Map<String, Object> map);

public UserEntity mapToEntity(Map<String, Object> map) {
    if ( map == null ) return null;
    return new UserEntity(); // 属性全都没赋值！
}

import cn.hutool.core.bean.BeanUtil;
import cn.hutool.core.bean.copier.CopyOptions;

@Mapper(componentModel = "spring")
public interface UserMapper {

    // ... 其他方法 ...

    /**
     * 场景二：Map <String, Object> -> Bean
     * 痛点解决：利用 default 方法 + Hutool 反射实现
     * 价值：对外屏蔽了实现细节，Service 层依然只调用 UserMapper
     */
    default UserEntity mapToEntity(Map<String, Object> map) {
        if (map == null) {
            return null;
        }
        // 使用 Hutool 的 BeanUtil，支持驼峰/下划线自动转换
        // 配置项表示忽略转换错误与 忽略 null 值
        return BeanUtil.toBean(map, UserEntity.class, CopyOptions.create().ignoreError().ignoreNullValue());
    }
}

@GetMapping("/testMap")
public Map<String, Object> testMap() {
    Map<String, Object> result = new LinkedHashMap<>();

    // 1. 验证 Map <Date> -> Map <String>
    Map<String, LocalDateTime> sourceMap = new HashMap<>();
    sourceMap.put("startTime", LocalDateTime.now());
    // MapStruct 自动处理格式化
    Map<String, String> formattedMap = userMapper.mapValueFormatting(sourceMap);
    result.put("scene1_formatting", formattedMap);

    // 2. 验证 Map <Object> -> Bean
    Map<String, Object> inputMap = new HashMap<>();
    inputMap.put("username", "map_user");
    inputMap.put("emailAddress", "map@test.com"); // 注意：BeanUtil 支持属性自动匹配
    inputMap.put("age", 18); // 多余字段，应该被忽略
    
    // Hutool 兜底处理动态转换
    UserEntity entity = userMapper.mapToEntity(inputMap);
    result.put("scene2_bean", entity);

    return result;
}

@Mapper(
    componentModel = "spring",
    // 针对 List/Set 返回空集合
    nullValueIterableMappingStrategy = NullValueIterableMappingStrategy.RETURN_DEFAULT,
    // 针对 Map 返回空 Map
    nullValueMapMappingStrategy = NullValueMapMappingStrategy.RETURN_DEFAULT
)
public interface BaseMapper {
    // ...
}

// 1. 基础的 List 转换 (MapStruct 自动生成)
// 这是地基，必须保留，供下面的 default 方法调用
List<UserVO> toVOList(List<UserEntity> entityList);

/**
 * 2. 高级聚合：List -> Map <Long, UserVO>
 * 利用 Java 8 default 方法，结合 MapStruct 和 Stream API
 */
default Map<Long, UserVO> toVOMap(List<UserEntity> entityList) {
    // 1. 安全防御：复用空集合策略
    if (entityList == null || entityList.isEmpty()) {
        return java.util.Collections.emptyMap();
    }
    
    // 2. 调用 MapStruct 生成的方法，先完成 Object -> Object 的属性转换
    List<UserVO> voList = toVOList(entityList);
    
    // 3. 使用 Stream API 进行聚合
    return voList.stream()
            .collect(java.util.stream.Collectors.toMap(
                    UserVO::getId,       // Key: 使用 ID
                    vo -> vo,            // Value: VO 对象本身
                    // MergeFunction (冲突解决策略): 
                    // 如果数据库中意外出现了重复 ID (脏数据)，取第一个，防止抛出 IllegalStateException
                    (v1, v2) -> v1       
            ));
}

// ... 注入 UserMapper

/**
 * 验证场景 1：List 转换与空值策略
 * 预期：
 * 1. 正常数据正常转换
 * 2. 传入 null 时，返回 [] 而不是 null
 */
@GetMapping("/list")
public List<UserVO> testList(@RequestParam(required = false) boolean mockNull) {
    if (mockNull) {
        // 测试空值策略：传入 null
        return userMapper.toVOList(null);
    }

    // 模拟数据
    List<UserEntity> list = new ArrayList<>();
    UserEntity u1 = new UserEntity();
    u1.setId(1L);
    u1.setEmailAddress("user1@test.com");
    
    UserEntity u2 = new UserEntity();
    u2.setId(2L);
    // u2 没有 email，测试 List 循环中的默认值逻辑是否生效
    
    list.add(u1);
    list.add(u2);
    
    return userMapper.toVOList(list);
}

/**
 * 验证场景 2：Stream 聚合 (List -> Map)
 * 预期：返回以 ID 为 Key 的 JSON 对象
 */
@GetMapping("/mapAggregate")
public Map<Long, UserVO> testMapAggregate() {
    List<UserEntity> list = new ArrayList<>();
    
    UserEntity u1 = new UserEntity();
    u1.setId(100L);
    u1.setUsername("Admin");

    UserEntity u2 = new UserEntity();
    u2.setId(200L);
    u2.setUsername("Guest");
    
    // 模拟脏数据：重复 ID，验证 toMap 的 mergeFunction 是否生效
    UserEntity u3_duplicate = new UserEntity();
    u3_duplicate.setId(100L); 
    u3_duplicate.setUsername("Admin_Duplicate");

    list.add(u1);
    list.add(u2);
    list.add(u3_duplicate);

    return userMapper.toVOMap(list);
}

// UserMapper.java

// 1. 定义单对象转换 (基础)
UserVO toVO(UserEntity entity);

// 2. 定义列表转换 (核心)
// MapStruct 自动生成循环代码，并复用 toVO 的配置
List<UserVO> toVOList(List<UserEntity> entityList);

// UserMapper.java

@Mapper(
    componentModel = "spring",
    // 核心配置：List/Set 入参为 null 时，返回 new ArrayList<>()
    nullValueIterableMappingStrategy = NullValueIterableMappingStrategy.RETURN_DEFAULT,
    // 核心配置：Map 入参为 null 时，返回 new LinkedHashMap<>()
    nullValueMapMappingStrategy = NullValueMapMappingStrategy.RETURN_DEFAULT
)
public interface UserMapper {
    // ...
}

// UserMapper.java

// 1. 基础转换 (由 MapStruct 实现)
List<UserVO> toVOList(List<UserEntity> list);

// 2. 自定义聚合 (由 Java 8 Default 方法实现)
default Map<Long, UserVO> toVOMap(List<UserEntity> list) {
    if (list == null) return Collections.emptyMap();
    
    return toVOList(list).stream() // 先转换内容
        .collect(Collectors.toMap(
            UserVO::getId,         // Key: 用户 ID
            vo -> vo,              // Value: VO 对象
            (v1, v2) -> v1         // Merge: 若 ID 重复，取第一个 (防崩溃)
        ));
}

// UserMapper.java

// 引入 Hutool 的 BeanUtil
import cn.hutool.core.bean.BeanUtil;

default UserEntity mapToEntity(Map<String, Object> map) {
    if (map == null) return null;
    
    // 使用反射工具兜底，实现动态 Key 匹配
    // ignoreError: 忽略转换失败的字段
    return BeanUtil.toBean(map, UserEntity.class);
}

// 1. 导入 System 类，以便在表达式中使用
@Mapper(componentModel = "spring", imports = {System.class}) 
public interface UserMapper {

    @Mappings({
        // 2. 注入 Java 代码：调用 System.currentTimeMillis()
        @Mapping(target = "serverTime", expression = "java(System.currentTimeMillis())"),
        
        // 3. 引用 source 参数：直接使用 source.getUsername()
        // 注意：这里的 "entity" 是方法参数名
        @Mapping(target = "welcomeMessage", expression = "java(\"Hello, \" + entity.getUsername())")
    })
    UserVO toVO(UserEntity entity);
}

// UserMapperImpl.java
userVO.setServerTime( System.currentTimeMillis() );
userVO.setWelcomeMessage( "Hello, " + entity.getUsername() );

@Mapper(componentModel = "spring")
public interface UserMapper {

    // 1. 定义一个具名方法：使用 @Named 标记
    @Named("maskPhone")
    default String maskPhone(String phone) {
        if (phone == null || phone.length() != 11) return phone;
        return phone.replaceAll("(\\d{3})\\d{4}(\\d{4})", "$1****$2");
    }

    @Mappings({
        // 2. 指定使用 "maskPhone" 规则
          @Mapping(source = "phoneNumber", target = "phoneNumber", qualifiedByName = "maskPhone"),
        
        // 3. 未指定 qualifiedByName，默认使用直连赋值
        @Mapping(source = "username", target = "username") 
    })
    UserVO toVO(UserEntity source);
}

@Service
public class DeptService {
    public String getDeptName(Long deptId) {
        return "技术部-" + deptId; // 模拟查库返回
    }
}

// 1. 改为 abstract class
@Mapper(componentModel = "spring")
public abstract class UserMapper {

    // 2. 注入 Service (使用 Autowired)
    @Autowired
    protected DeptService deptService;

    // 3. 定义抽象方法，交给 MapStruct 实现基础映射
    // 使用 expression 调用内部方法
    @Mapping(target = "deptName", expression = "java(convertDeptName(entity.getDeptId()))")
    public abstract UserVO toVO(UserEntity entity);

    // 4. 自定义转换逻辑：调用 Service
    protected String convertDeptName(Long deptId) {
        if (deptId == null) return "未知部门";
        return deptService.getDeptName(deptId);
    }
}

@Component
public class UserMapperImpl extends UserMapper {
    @Override
    public UserVO toVO(UserEntity entity) {
        // ...
        // 生成的代码直接调用了父类的 convertDeptName 方法
        // 而父类通过 Spring 注入持有了 DeptService
        userVO.setDeptName( convertDeptName(entity.getDeptId()) ); 
        return userVO;
    }
}

@AfterMapping // 映射完成后自动回调
protected void calculateVipLevel(UserEntity source, @MappingTarget UserVO target) {
    if (source.getBalance() != null && source.getBalance().doubleValue() > 10000) {
        target.setVipLevel("DIAMOND");
    } else {
        target.setVipLevel("NORMAL");
    }
}

public UserVO toVO(UserEntity entity) {
    UserVO userVO = new UserVO();
    // ... 自动映射逻辑 ...
    
    // 最后一步：调用后置处理
    calculateVipLevel( entity, userVO ); 
    
    return userVO;
}

@Data
public class AccountEntity {
    private String bankCard;
    private BigDecimal creditScore;
}

@Mappings({
    // 1. 指定 source 参数名：user.id -> id
    @Mapping(source = "user.id", target = "id"),
    // 2. 指定 source 参数名：account.bankCard -> cardNo
    @Mapping(source = "account.bankCard", target = "cardNo")
})
// 传入两个源对象：user 和 account
public abstract UserDetailVO toDetailVO(UserEntity user, AccountEntity account);

@Mappings({
    @Mapping(target = "id", ignore = true), // ID 不允许修改
    @Mapping(target = "createTime", ignore = true) // 创建时间不允许修改
})
// 1. @BeanMapping(nullValuePropertyMappingStrategy = IGNORE)
// 关键配置：DTO 中为 null 的字段，不要覆盖 Entity 中的旧值
@BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)

// 2. @MappingTarget 标记这是要被更新的目标对象，而不是源对象
public abstract void updateEntityFromDto(UserDTO dto, @MappingTarget UserEntity entity);

public void updateEntityFromDto(UserDTO dto, UserEntity entity) {
    if ( dto == null ) return;

    if ( dto.getUsername() != null ) { // 自动生成了 null 判断
        entity.setUsername( dto.getUsername() );
    }
    // ...
}

// ... 注入 UserMapper

@PutMapping("/update/{id}")
public UserEntity testUpdate(@PathVariable Long id, @RequestBody UserDTO dto) {
    // 1. 模拟查库 (Old State)
    UserEntity entity = new UserEntity();
    entity.setId(id);
    entity.setUsername("old_name");
    entity.setEmailAddress("old@test.com");
    
    // 2. 增量更新 (只更新 dto 中不为 null 的字段)
    userMapper.updateEntityFromDto(dto, entity);
    
    // 3. 返回更新后的对象
    return entity;
}

@Mapper(componentModel = "spring", imports = {UUID.class}) // 1. 记得导入类
public interface UserMapper {

    @Mappings({
        // 2. 直接写 Java 代码 (注意：编译器不检查字符串内容的语法)
        @Mapping(target = "uuid", expression = "java(UUID.randomUUID().toString())"),
        @Mapping(target = "ts", expression = "java(System.currentTimeMillis())")
    })
    UserVO toVO(UserEntity entity);
}

// 1. 定义两个不同逻辑的方法，用 @Named 区分
@Named("mask")
default String mask(String str) {
    return str == null ? null : str.replaceAll("(\\d{3})\\d{4}(\\d{4})", "$1****$2");
}
// 2. 在映射时明确指定使用哪一个
@Mapping(source = "mobile", target = "mobile", qualifiedByName = "mask")
UserVO toMaskedVO(UserEntity entity);

@Mapper(componentModel = "spring")
public abstract class UserMapper { // 1. 必须是抽象类

    @Autowired
    protected DeptService deptService; // 2. 注入 Service (必须是 protected)

    @Mapping(target = "deptName", expression = "java(deptService.getName(entity.getDeptId()))")
    public abstract UserVO toVO(UserEntity entity);
}

public abstract class UserMapper {

    public abstract UserVO toVO(UserEntity entity);

    // 自动映射完成后，MapStruct 会自动调用此方法
    @AfterMapping
    protected void after(@MappingTarget UserVO vo, UserEntity entity) {
        if (entity.getBalance() > 10000) {
            vo.setVipLevel("DIAMOND");
        } else {
            vo.setVipLevel("NORMAL");
        }
    }
}

// 1. 核心策略：源字段为 null 时，忽略赋值 (即保留目标对象原值)
@BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
// 2. @MappingTarget 标记 entity 是被更新的对象
void updateEntity(UserDTO dto, @MappingTarget UserEntity entity);

package com.example.demo.domain.bo;

import lombok.Data;

@Data
public class UserBO {
    /** 用户名 */
    private String username;
    
    /** 手机号 */
    private String phone;
    
    /** 密码 (业务层处理加密) */
    private String password;
    
    /** 来源 (如: Android, iOS) */
    private String source;
}

package com.example.demo.client.dto;

import com.example.demo.domain.bo.UserBO;
import io.github.linpeilie.annotations.AutoMapper;
import lombok.Data;

@Data
// 核心注解：声明当前类 (DTO) 可以转换为 目标类 (BO)
// MSP 会在编译期自动生成 UserCreateDTOToUserBOMapper 接口及其实现
@AutoMapper(target = UserBO.class)
public class UserCreateDTO {
    
    private String username;
    
    private String phone;
    
    private String password;
    
    // 假设前端传入的字段叫 "platform"，而 BO 中叫 "source"
    // 我们暂时不处理这个异名映射，先观察默认行为
    private String platform;
}

package com.example.demo.controller;

import com.example.demo.client.dto.UserCreateDTO;
import com.example.demo.domain.bo.UserBO;
import io.github.linpeilie.Converter; // 1. 引入 MSP 核心转换器
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/users")
@RequiredArgsConstructor
public class UserRegistrationController {

    // 2. 注入全局转换器 (底层会自动路由到生成的 Mapper)
    private final Converter converter;

    @PostMapping("/register")
    public UserBO register(@RequestBody UserCreateDTO dto) {
        // 3. 模拟接收到的数据
        System.out.println("接收到 DTO: " + dto);

        // 4. 执行转化：DTO -> BO
        // 语法：converter.convert(源对象, 目标类.class)
        UserBO bo = converter.convert(dto, UserBO.class);
        
        System.out.println("转化为 BO: " + bo);
        
        // 返回 BO 仅供测试验证
        return bo;
    }
}

// 自动生成的代码片段
@Component
public class UserCreateDTOToUserBOMapper extends BaseMapper<UserCreateDTO, UserBO> {
    @Override
    public UserBO convert(UserCreateDTO source, UserBO target) {
        // ... 自动生成的 setter/getter 代码 ...
        // 注意：由于 platform 和 source 名字不同，这里并没有生成赋值代码
        target.setUsername(source.getUsername());
        // ...
        return target;
    }
}

package com.example.demo.config;

import io.github.linpeilie.annotations.MapperConfig;
import org.mapstruct.ReportingPolicy;

// 全局配置：作用于所有自动生成的 Mapper
@MapperConfig(
    // 1. 当源对象 (DTO) 有字段未被映射到目标对象时 -> 忽略 (DTO 字段通常多于 BO)
    unmappedSourcePolicy = ReportingPolicy.IGNORE,
    
    // 2. 当目标对象 (BO) 有字段未被赋值时 -> 警告 (防止业务属性遗漏)
    unmappedTargetPolicy = ReportingPolicy.WARN
)
public class MapStructPlusConfig {
    // 这是一个标记类，不需要写代码
}

// 1. DTO 定义 (Source)
@Data
@AutoMapper(target = UserBO.class) // 指向目标
public class UserRegisterDTO {
    private String username;
}

// 2. BO 定义 (Target)
@Data
public class UserBO {
    private String username;
}

// 3. Controller 调用
@Autowired Converter converter;
UserBO bo = converter.convert(dto, UserBO.class);