@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);
    }
}