# Java Bean 拷贝还在手写 set/get？JQuickBeanCopyUtils 详细使用教程，附完整示例

**Git 地址：** https://github.com/paohaijiao/javelin

**Maven 坐标：**

```xml
<dependency>
    <groupId>io.github.paohaijiao</groupId>
    <artifactId>javelin-core</artifactId>
    <version>2.5.0</version>
</dependency>
```

## 前言

在 Java 后端开发里，Bean 拷贝几乎每天都在写。

比如：

- Entity 转 DTO
- DTO 转 VO
- 请求对象转数据库对象
- 查询结果转响应对象
- 更新接口只覆盖非 null 字段

如果每次都手写 `setXxx/getXxx`，代码不但重复，而且字段一多就很容易漏。

这篇文章就从程序员实战角度，详细讲清楚 `javelin-core` 里的 `JQuickBeanCopyUtils` 怎么用？

## 一、JQuickBeanCopyUtils 是什么

`JQuickBeanCopyUtils` 是 `javelin-core` 提供的一个轻量 Bean 拷贝工具类，适合处理同名属性之间的浅拷贝。

它主要解决这几类需求：

- 单个对象拷贝
- 新对象创建后拷贝
- 集合批量拷贝
- 忽略字段拷贝
- 只合并非 null 字段
- 通过 `Supplier` 方式快速创建目标对象

从实现上看，常规拷贝优先使用 ASM 生成的复制逻辑，适合高频调用；忽略字段和 `mergeNonNull` 这类场景则保留了反射处理路径，语义更稳。

## 二、先看一个最小可用示例

### 1. 源对象和目标对象定义

```java
public class UserEntity {
    private Long id;
    private String name;
    private Integer age;
    private String email;
    private Boolean active;

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    public Boolean getActive() {
        return active;
    }

    public void setActive(Boolean active) {
        this.active = active;
    }
}
```

```java
public class UserVO {
    private Long id;
    private String name;
    private Integer age;
    private String email;
    private Boolean active;

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    public Boolean getActive() {
        return active;
    }

    public void setActive(Boolean active) {
        this.active = active;
    }
}
```

### 2. 最基础的对象拷贝

```java
UserEntity entity = new UserEntity();
entity.setId(1L);
entity.setName("张三");
entity.setAge(28);
entity.setEmail("zhangsan@example.com");
entity.setActive(true);

UserVO vo = new UserVO();
JQuickBeanCopyUtils.copy(entity, vo);

System.out.println(vo.getName());
System.out.println(vo.getEmail());
```

输出效果：

```java
张三
zhangsan@example.com
```

这类写法适合已经有目标对象实例的场景。

## 三、JQuickBeanCopyUtils 的核心用法详解

### 1. 复制到已有对象

```java
UserVO vo = new UserVO();
JQuickBeanCopyUtils.copy(entity, vo);
```

适合场景：

- 把查询对象转成返回对象
- 对已有对象重新填充数据
- 二次包装接口返回值

### 2. 直接创建新对象并返回

如果你不想先手动 `new UserVO()`，可以直接传目标类型。

```java
UserVO vo = JQuickBeanCopyUtils.copy(entity, UserVO.class);
```

这是业务开发里最顺手的写法之一，尤其适合 Service 层返回 DTO、VO。

### 3. 忽略指定字段

很多场景下，你不想把某些字段带出去，比如密码、逻辑删除标记、更新时间。

```java
UserVO vo = JQuickBeanCopyUtils.copy(
    entity,
    UserVO.class,
    "email",
    "active"
);
```

或者拷贝到已有对象时忽略字段：

```java
UserVO vo = new UserVO();
JQuickBeanCopyUtils.copy(entity, vo, "email", "active");
```

这类写法尤其适合：

- 对外接口隐藏敏感字段
- 避免覆盖某些已有值
- 导出对象时做字段裁剪

### 4. 批量拷贝 List 集合

真实业务里，更常见的是批量转换。

```java
List<UserEntity> entityList = Arrays.asList(entity1, entity2, entity3);
List<UserVO> voList = JQuickBeanCopyUtils.copyToList(entityList, UserVO.class);
```

如果需要忽略字段：

```java
List<UserVO> voList = JQuickBeanCopyUtils.copyToList(
    entityList,
    UserVO.class,
    "email"
);
```

这个接口很适合：

- 分页结果转换
- 查询列表返回封装
- 批量导出前的数据整理

### 5. 使用 Supplier 方式便捷创建对象

这是一个非常实用的便捷访问方式。

```java
List<UserVO> voList = JQuickBeanCopyUtils.copyToList(
    entityList,
    UserVO::new
);
```

为什么这个写法值得单独强调？

- 比传 `Class` 更自然
- 和 Java 8 方法引用风格一致
- 方便接入自定义对象初始化逻辑

比如你可以扩展成：

```java
List<UserVO> voList = JQuickBeanCopyUtils.copyToList(
    entityList,
    () -> {
        UserVO vo = new UserVO();
        vo.setActive(false);
        return vo;
    }
);
```

这在某些默认值初始化场景里会很舒服。

### 6. 只合并非 null 字段

这是更新接口最实用的能力之一。

先看请求对象：

```java
public class UserUpdateReq {
    private String name;
    private Integer age;
    private String email;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }
}
```

再看更新逻辑：

```java
UserEntity dbUser = new UserEntity();
dbUser.setId(100L);
dbUser.setName("原用户名");
dbUser.setAge(30);
dbUser.setEmail("old@example.com");

UserUpdateReq req = new UserUpdateReq();
req.setName("新用户名");
req.setEmail("new@example.com");

JQuickBeanCopyUtils.mergeNonNull(req, dbUser);
```

执行后的结果：

- `name` 被更新为 `新用户名`
- `email` 被更新为 `new@example.com`
- `age` 因为请求里没传，不会被覆盖
- `id` 继续保留原值

这类能力非常适合：

- 用户资料部分更新
- 配置项局部更新
- 审核状态对象的补丁更新

## 四、详细业务示例

### 示例 1：Entity 转 DTO

```java
public UserDTO getUserDetail(Long userId) {
    UserEntity entity = userRepository.findById(userId);
    return JQuickBeanCopyUtils.copy(entity, UserDTO.class);
}
```

这个写法可以把原来几十行 setter 压缩成一行。

### 示例 2：分页列表转换

```java
public List<UserVO> listUsers() {
    List<UserEntity> entityList = userRepository.findAll();
    return JQuickBeanCopyUtils.copyToList(entityList, UserVO.class);
}
```

### 示例 3：返回对象过滤敏感字段

```java
public UserVO getSafeUser(Long userId) {
    UserEntity entity = userRepository.findById(userId);
    return JQuickBeanCopyUtils.copy(entity, UserVO.class, "password", "deleted", "updateTime");
}
```

### 示例 4：更新接口局部覆盖

```java
public void updateUser(UserUpdateReq req, UserEntity entity) {
    JQuickBeanCopyUtils.mergeNonNull(req, entity);
    userRepository.update(entity);
}
```

## 五、JQuickBeanCopyUtils 的使用建议

### 1. 适合同结构对象

如果源对象和目标对象字段名大体一致，这个工具会非常顺手。

### 2. 它是浅拷贝

对象字段和集合字段复制的是引用，不会自动深拷贝。

比如：

```java
userVO.setAddress(userEntity.getAddress());
```

这类字段本质上是同一个引用。

### 3. 目标类型最好有无参构造

使用 `copy(source, Target.class)` 时，目标对象需要支持无参创建。

### 4. 忽略字段建议显式写清楚

像 `password`、`deleted`、`updateTime` 这类字段，建议明确写进忽略列表，不要依赖调用方记忆。

## 六、为什么程序员会喜欢这个工具

从工程角度看，`JQuickBeanCopyUtils` 有几个明显优势：

- API 简单，几乎不用学习成本
- 覆盖了对象拷贝的主流场景
- 集合转换很直接
- `mergeNonNull` 非常贴合更新接口
- `Supplier` 方法引用写法很利落

尤其对于 Java 后端 CRUD 项目，它的收益非常直接，就是减少重复代码。

## 七、推荐的项目使用姿势

可以按下面这套思路统一团队写法：

- 单对象转换用 `copy(source, Target.class)`
- 已有目标对象填充用 `copy(source, target)`
- 列表转换统一用 `copyToList`
- 更新接口统一考虑 `mergeNonNull`
- 对外对象返回时显式忽略敏感字段

这样代码会整齐很多。

## 八、完整快速示例

```java
UserVO vo = JQuickBeanCopyUtils.copy(entity, UserVO.class);

List<UserVO> voList = JQuickBeanCopyUtils.copyToList(entityList, UserVO::new);

UserVO safeVo = JQuickBeanCopyUtils.copy(entity, UserVO.class, "password", "deleted");

JQuickBeanCopyUtils.mergeNonNull(updateReq, entity);
```

## 九、总结

如果你经常写 DTO、VO、Entity 转换，又不想被一堆重复 `set/get` 拖慢开发节奏，那么 `JQuickBeanCopyUtils` 是一个非常值得放进项目里的轻量工具。

它最有价值的地方不只是“能拷贝”，而是把程序员最常写的那几种转换场景都覆盖到了，尤其是：

- 新对象转换
- 批量列表转换
- 忽略字段
- 非 null 合并更新
- `Supplier` 便捷访问方式

对于日常 Java 后端开发来说，这类工具越稳定、越顺手，团队整体效率就越高。

## 关键词

JQuickBeanCopyUtils 使用教程、Java Bean 拷贝工具、Java DTO 转 VO、Java 对象拷贝工具、copyToList 用法、mergeNonNull 用法、Java 更新接口对象合并、javelin-core 教程、Java 开发效率工具、BeanCopier 工具类

Git 地址： https://github.com/paohaijiao/javelin

Java Bean 拷贝工具推荐：JQuickBeanCopyUtils 的使用与避坑指南

人工智能

JQuickBeanCopyUtils是javelin-core提供的轻量级JavaBean拷贝工具，支持对象复制、List批量转换、忽略字段、mergeNonNull非空合并及Supplier创建，替代手写set/get，简化DTO/VO转换，附GitHub示例与Maven坐标。

代码解释

数据库

GitHub

Java

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Java Bean 拷贝工具推荐：JQuickBeanCopyUtils 的使用与避坑指南-腾讯云开发者社区-腾讯云

Java Bean 拷贝工具推荐：JQuickBeanCopyUtils 的使用与避坑指南

Java Bean 拷贝工具推荐：JQuickBeanCopyUtils 的使用与避坑指南

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐