【Java开发--对象converter转换规范实践】

写在开始：
1️⃣本文仅用作个人java日常开发记录学习使用，如果涉及版权或者其他问题，及时联系小编修改或者下架，多谢
2️⃣摘要 :本文主要介绍Java开发过程中–对象converter转换规范的小小实践,如果赶时间可以直接阅读第一部分 show code就可以哈

一、Show Code

public class TestBOConverter {
    // ✅ 1. 基础版本：一一复制属性
    public static TestBO of(TestDO testDO) {
        if (Objects.isNull(testDO)) {
            return null;
        }
        TestBO testBO = new TestBO();
        testBO.setId(testDO.getId());
        testBO.setName(testDO.getName());
        testBO.setCreateTime(testDO.getCreateTime());
        return testBO;
    }

 // 2. ✅ Builder模式：链式调用
    public static TestBO convert(TestDO testDO) {
        if (null == testDO) {
            return null;
        }
        return TestBO.builder().id(testDO.getId()).name(testDO.getName()).createTime(testDO.getCreateTime()).build();
    }
    // 或者
    // ✅ 提升可读性
    public static TestBO convert(TestDO testDO) {
        return Optional.ofNullable(testDO)
                       .map(d -> TestBO.builder()
                           .id(d.getId())
                           .name(d.getName())
                           .createTime(d.getCreateTime())
                           .build())
                       .orElse(null);
    }
 
}

import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.NullValueCheckStrategy;
import org.mapstruct.NullValueMappingStrategy;
import org.mapstruct.ReportingPolicy;
import org.mapstruct.factory.Mappers;

/**
 * Author: test
 * Date:   2025/5/15-17:21
 * ---------------------------------------
 * Desc:   TestBO 对象转换器，使用 MapStruct 实现自动映射
 */
@Mapper(
        unmappedTargetPolicy = ReportingPolicy.ERROR,
        nullValueCheckStrategy = NullValueCheckStrategy.ALWAYS,
        nullValueMappingStrategy = NullValueMappingStrategy.RETURN_NULL
)
public interface TestBOConverter {
    
    TestBOConverter INSTANCE = Mappers.getMapper(TestBOConverter.class);

    /**
     * ✅ MapStruct最佳实践
     * 将 TestDO 转换为 TestBO
     * 
     * @param source TestDO 源对象
     * @return TestBO 目标对象
     */
    @Mapping(target = "id", source = "id")
    @Mapping(target = "name", source = "name")
    @Mapping(target = "createTime", source = "createTime")
    TestBO of(TestDO source);
    
}

二、规范简介
日常Java开发涉及到大量的converter函数，本文档统一整理相关的规范，描述如下

1. 包名为 converter
2. 类名： {转换目标类}Converter 【所有Converter类必须放在{module}.converter包下】
3. 方法命名：1️⃣单一方法：of()2️⃣多场景方法：ofCreate()/ofUpdate()
4. 方法实现：1️⃣禁止使用BeanUtils.copyProperties2️⃣推荐使用mapStruct（使用mapstruct后，需要本地编译后review生成代码）3️⃣针对get/set风格的实现，代码生成推荐使用idea插件 GenerateAllSetter，推荐使用converterCheck注解进行检查

// ✅ 标准包结构
com
└── company
    └── order
        └── converter  // 专用converter包
            ├── OrderDTOConverter
            └── ProductVOConverter

// ❌ 错误示例
com.company.order.util.ConverterUtil  // 包位置错误

// ❌ 严禁使用BeanUtils
BeanUtils.copyProperties(source, target);

// ✅ 正确替代方案
@Mapper
public interface UserConverter {
    UserDTO toDTO(UserEntity entity);
}

三、三种实现方式比较

四、mapstruct简单说明

官方文档

https://mapstruct.org/documentation/stable/reference/html/

优势

1. 通过使用普通方法调用（settter/getter）而不是反射来快速执行
2. 编译时类型安全性：只能映射相互映射的对象和属性
3. 如果有如下问题，编译时会抛出异常3.1 映射不完整（并非所有目标属性都被映射）3.2 映射不正确（找不到正确的映射方法或类型转换）
4. 新增模型时减少手动编写重复代码
5. 修改模型字段时减少代码修改位置，避免遗漏

问题

• 有一定的学习成本
• 表达式在代码生成期不会做校验
• idea获取所有引用位置时，无法检测到
• 使用反射修改字段名称时无法自动修改注解里的参数

Maven基础配置

<!-- Maven依赖 -->
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct</artifactId>
    <version>1.5.5.Final</version>
</dependency>
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct-processor</artifactId>
    <version>1.5.5.Final</version>
</dependency>

Maven基础配置

@Mapper
public interface PersonDTOConverter {
    PersonConverter INSTANCT = Mappers.getMapper(PersonConverter.class);
	
	  @Mapping(target = "name", source = "personName")
	  @Mapping(target = "id", ignore = true) // 忽略id，不进行映射
    @Mapping(target = "describe", source = "describe", defaultValue = "默认值") // 指定默认值
    @Mapping(target = "createTime",expression = "java(new java.util.Date())") // 使用表达式
    @Mapping(target = "childs", defaultExpression = "java( com.google.common.collect.Lists.newArrayList() )") // 默认表达式
    @Mapping(target = "updateTime" ,source = "updateTime", dateFormat = "yyyy-MM-dd") // String到Date的转换
    PersonDTO of(Person person);

}

五、🔧 附录：常见问题解决方案

Q1 字段名称不一致怎么办？

@Mapper
public interface OrderConverter {
    @Mapping(source = "orderDate", target = "createTime")
    OrderDTO toDTO(OrderEntity entity);
}

Q2 如何转换集合对象？

@Mapper
public interface ProductConverter {
    List<ProductDTO> toDTOList(List<ProductEntity> entities);
}

Q3 需要自定义逻辑如何处理？

@Mapper
public interface UserConverter {
    default UserDTO toDTO(UserEntity entity) {
        UserDTO dto = new UserDTO();
        dto.setFullName(entity.getFirstName() + " " + entity.getLastName());
        // 其他自动映射字段...
        return dto;
    }
}

规范的价值在于让团队用同一种语言说话！ 👥💬

写在最后 ： 码字不易，如果认为不错或者对您有帮忙，希望读者动动小手，点赞或者关注哈，多谢