feat(dto): Enrich data conversion interface and add list copy methods

- Added copyList method to BaseMapper interface to convert object list in batch
- Added partialUpdate method in the ConversionMapper interface to partially update entity objects
- Optimized interface document annotations, clarifying the function and parameter meaning of the method
- Adjusted the order of generic parameters to improve code readability

forgeboot-webmvc/dto/src/main/kotlin/com/gewuyou/forgeboot/webmvc/dto/mapper/BaseMapper.kt

@@ -6,24 +6,44 @@ import org.mapstruct.NullValuePropertyMappingStrategy
 
 /**
  * Base Mapper（基础映射器）
+ * 提供基础的对象映射操作定义，包含合并、覆盖合并、单个对象拷贝及列表拷贝的方法。
  *
  * @since 2025-05-30 22:50:18
  * @author gewuyou
  */
-interface BaseMapper<T,S> {
+interface BaseMapper<S, T> {
     /**
-     * 合并 source 到 target，忽略 null 值
+     * 将 source 对象中的非 null 属性合并到 target 对象中。
+     * 注意：null 值的属性不会覆盖 target 中已有的值。
+     *
+     * @param target 目标对象，将被更新
+     * @param source 源对象，提供需要合并的数据
      */
     @BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
     fun mergeIgnoreNull(@MappingTarget target: T, source: S)
 
     /**
-     * 全量覆盖合并（source 字段即使为 null 也覆盖 target）
+     * 全量覆盖合并 source 到 target。
+     * 注意：即使 source 中的字段为 null，也会覆盖 target 中对应的字段。
+     *
+     * @param target 目标对象，将被更新
+     * @param source 源对象，提供需要合并的数据
      */
     fun overwriteMerge(@MappingTarget target: T, source: S)
 
     /**
-     * 拷贝 source 到新对象
+     * 将 source 对象的内容拷贝到一个新的 T 类型对象中。
+     *
+     * @param source 源对象，提供数据
+     * @return 返回一个新的目标类型对象
      */
     fun copy(source: S): T
+
+    /**
+     * 将源对象列表中的每个元素拷贝为新的目标类型对象，生成一个目标对象列表。
+     *
+     * @param sources 源对象列表
+     * @return 返回目标类型对象的列表
+     */
+    fun copyList(sources: List<S>): List<T>
 }

forgeboot-webmvc/dto/src/main/kotlin/com/gewuyou/forgeboot/webmvc/dto/mapper/ConversionMapper.kt

@@ -1,10 +1,15 @@
-package com.gewuyou.forgeboot.webmvc.dto.dto.mapper
+package com.gewuyou.forgeboot.webmvc.dto.mapper
+
+import org.mapstruct.BeanMapping
+import org.mapstruct.MappingTarget
+import org.mapstruct.NullValuePropertyMappingStrategy
 
 /**
- * 转换 映射器
+ * 转换映射器接口
  *
- * 定义了一个转换映射器接口，用于在实体类和数据传输对象（DTO）之间进行转换。
+ * 提供通用的实体类(Entity)与数据传输对象(DTO)之间的双向转换能力。
- * 这个接口定义了四个基本转换方法：实体到DTO、DTO到实体、实体列表到DTO列表和DTO列表到实体列表。
+ * 该接口定义了基础的数据转换方法，包括单个对象和集合对象的转换，
+ * 并支持部分更新操作（忽略空值属性）。
  *
  * @param <Entity> 实体类类型
  * @param <Dto> 数据传输对象类型
@@ -14,34 +19,45 @@ package com.gewuyou.forgeboot.webmvc.dto.dto.mapper
  */
 interface ConversionMapper<Entity, Dto> {
     /**
-     * 将实体对象转换为DTO对象
+     * 将实体对象转换为对应的DTO对象
      *
-     * @param entity 实体对象
+     * @param entity 需要转换的实体对象
      * @return 转换后的DTO对象
      */
     fun toDto(entity: Entity): Dto
 
     /**
-     * 将DTO对象转换为实体对象
+     * 将DTO对象转换为对应的实体对象
      *
-     * @param dto DTO对象
+     * @param dto 需要转换的DTO对象
      * @return 转换后的实体对象
      */
     fun toEntity(dto: Dto): Entity
 
     /**
-     * 将实体对象列表转换为DTO对象列表
+     * 将实体对象列表转换为对应的DTO对象列表
      *
-     * @param entityList 实体对象列表
+     * @param entityList 需要转换的实体对象列表
      * @return 转换后的DTO对象列表
      */
     fun toDtoList(entityList: List<Entity>): List<Dto>
 
     /**
-     * 将DTO对象列表转换为实体对象列表
+     * 将DTO对象列表转换为对应的实体对象列表
      *
-     * @param dtoList DTO对象列表
+     * @param dtoList 需要转换的DTO对象列表
      * @return 转换后的实体对象列表
      */
     fun toEntityList(dtoList: List<Dto>): List<Entity>
+
+    /**
+     * 使用非空属性对实体进行部分更新
+     *
+     * 注意：此操作不会覆盖实体中为空的属性
+     *
+     * @param dto 需要用于更新的DTO对象
+     * @param entity 需要被更新的实体对象
+     */
+    @BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
+    fun partialUpdate(dto: Dto, @MappingTarget entity: Entity)
 }