Spring Boot（Kotlin）用MapStruct映射含嵌套集合的复杂DTO至实体

一、基础依赖配置 #

Kotlin环境下需要启用kapt插件来处理MapStruct的注解处理器，同时指定Spring作为组件模型，方便依赖注入：

plugins {
    kotlin("kapt") version "你的Kotlin版本"
}

dependencies {
    implementation("org.mapstruct:mapstruct:1.5.5.Final")
    kapt("org.mapstruct:mapstruct-processor:1.5.5.Final")
    // Spring集成可选，用于生成Spring Bean类型的Mapper
    implementation("org.mapstruct:mapstruct-spring:1.5.5.Final")
}

kapt {
    arguments {
        arg("mapstruct.defaultComponentModel", "spring")
    }
}

二、嵌套集合映射实现 #

以订单-订单项的嵌套集合场景为例，直接定义Mapper接口即可，MapStruct会自动处理集合的循环映射：

1. 定义实体与DTO #

// 子实体
data class OrderItem(
    val id: Long?,
    val productName: String,
    val quantity: Int
)

// 父实体
data class Order(
    val id: Long?,
    val orderNumber: String,
    val items: List<OrderItem>
)

// 子DTO
data class OrderItemDTO(
    val productName: String,
    val quantity: Int,
    val productCode: String // DTO特有字段
)

// 父DTO
data class OrderDTO(
    val orderNumber: String,
    val items: List<OrderItemDTO>
)

2. 编写Mapper接口 #

@Mapper(componentModel = "spring")
interface OrderMapper {
    // 单个子DTO到子实体的映射
    @Mapping(target = "id", ignore = true) // 实体ID由数据库生成，忽略DTO字段
    fun toOrderItem(itemDTO: OrderItemDTO): OrderItem

    // 集合映射：MapStruct自动调用上面的单个映射方法
    fun toOrderItemList(itemDTOs: List<OrderItemDTO>): List<OrderItem>

    // 主映射方法，嵌套集合会自动触发集合映射逻辑
    @Mapping(target = "id", ignore = true)
    fun toOrder(orderDTO: OrderDTO): Order

    // 反向映射同理
    fun toOrderDTO(order: Order): OrderDTO
}

3. 自定义复杂转换逻辑 #

如果需要对字段做业务转换（比如用productCode获取真实商品名称），可以关联Spring Bean实现：

@Mapper(componentModel = "spring", uses = [ProductService::class])
interface OrderMapper {
    @Mapping(target = "id", ignore = true)
    @Mapping(target = "productName", source = "productCode", qualifiedByName = ["getProductNameByCode"])
    fun toOrderItem(itemDTO: OrderItemDTO): OrderItem

    // ...其他映射方法
}

// 对应的Spring业务Bean
@Service
class ProductService {
    @Named("getProductNameByCode")
    fun getProductNameByCode(productCode: String): String {
        // 从数据库/配置中心获取商品名称的业务逻辑
        return "商品_$productCode"
    }
}

三、最佳实践 #

• 明确组件模型：始终指定componentModel = "spring"，让Mapper成为Spring Bean，避免手动实例化
• 拆分Mapper职责：复杂嵌套结构拆分多个小Mapper（比如OrderItemMapper和OrderMapper），通过uses = []关联，提升可读性
• 忽略冗余字段：对实体自增ID、数据库默认值字段，用@Mapping(ignore = true)明确忽略，避免映射错误
• 空集合处理：MapStruct默认会将null集合转为空List，无需手动判空；如需自定义可添加@IterableMapping(nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT)
• 测试映射逻辑：编写单元测试验证嵌套集合、自定义转换的结果，确保映射准确性：

@SpringBootTest
class OrderMapperTest {
    @Autowired
    lateinit var orderMapper: OrderMapper

    @Test
    fun testNestedMapping() {
        val itemDTO = OrderItemDTO("测试商品", 2, "P001")
        val orderDTO = OrderDTO("ORD-20240501", listOf(itemDTO))
        val order = orderMapper.toOrder(orderDTO)
        
        assertEquals("ORD-20240501", order.orderNumber)
        assertEquals(1, order.items.size)
        assertEquals("测试商品", order.items[0].productName)
    }
}

• 避免Mapper写业务逻辑：Mapper仅负责字段转换，复杂业务逻辑放在Service层或专门的转换类中

内容的提问来源于stack exchange，提问作者JavoHyperion