告别MyBatis-Plus的复杂SQL，我用QueryDSL-JPA重构了公司老项目（SpringBoot 2.7实战）

从MyBatis-Plus到QueryDSL-JPA：SpringBoot项目中复杂SQL的优雅重构实践

技术选型的十字路口

三年前接手公司电商后台系统时，MyBatis-Plus（简称MP）还是当时最合理的选择。但随着业务复杂度呈指数级增长，我们逐渐陷入了"SQL地狱"——每个新需求都意味着要在XML里新增动态SQL片段，或是用Java代码拼接Where条件字符串。直到某次灰度发布，因为一个字段名拼写错误导致线上查询异常，团队终于下定决心寻找更类型安全的解决方案。

QueryDSL-JPA的出现像是一剂良药。它不仅解决了类型安全问题，更重要的是让我们的代码重新获得了IDE的智能提示和编译期检查。在SpringBoot 2.7环境下进行全量迁移后，复杂查询的代码量减少了40%，而可维护性却显著提升。本文将分享这次技术重构的完整心路历程。

1. 为什么放弃MyBatis-Plus？

1.1 动态查询的维护噩梦

在订单管理模块中，我们需要根据十多个可选条件组合查询订单。MP的实现方式通常是这样的：

public List<Order> queryOrders(OrderQueryDTO dto) { QueryWrapper<Order> wrapper = new QueryWrapper<>(); if (StringUtils.isNotBlank(dto.getOrderNo())) { wrapper.like("order_no", dto.getOrderNo()); } if (dto.getStatus() != null) { wrapper.eq("status", dto.getStatus()); } // 更多条件判断... return orderMapper.selectList(wrapper); }

这种模式存在三个致命问题：

• 字段名以字符串形式存在，重命名时IDE无法检测
• 条件组合逻辑难以复用
• 复杂查询（如子查询、联表）可读性急剧下降

1.2 类型安全缺失的代价

我们曾因为一个字段类型不匹配导致全表扫描：

wrapper.eq("user_id", "12345"); // 本应是Long类型

这种错误直到运行时才会暴露，而在QueryDSL中根本不可能发生，因为：

// 编译就会报错 queryFactory.selectFrom(qOrder) .where(qOrder.userId.eq("12345")) // 类型不匹配

2. QueryDSL-JPA核心优势解析

2.1 类型安全的查询构建

QueryDSL通过APT在编译期生成Q类（如QOrder），所有查询都基于这些元模型：

// 查询id大于100的活跃用户 List<User> users = queryFactory.selectFrom(qUser) .where(qUser.id.gt(100L) .and(qUser.isActive.isTrue())) .fetch();

这种写法的优势显而易见：

1. 字段名和类型在编译期检查
2. IDE支持代码自动补全
3. 重构友好（重命名字段会同步更新查询）

2.2 复杂查询的优雅表达

对比多表关联查询的实现差异：

MyBatis-Plus方案：

<!-- XML中 --> <select id="selectUserWithOrders" resultMap="userWithOrders"> SELECT u.*, o.* FROM user u LEFT JOIN order o ON u.id = o.user_id WHERE u.status = #{status} <if test="minOrderCount != null"> AND (SELECT COUNT(*) FROM order WHERE user_id = u.id) >= #{minOrderCount} </if> </select>

QueryDSL方案：

List<Tuple> results = queryFactory.select( qUser, qOrder.count()) .from(qUser) .leftJoin(qOrder).on(qUser.id.eq(qOrder.userId)) .where(qUser.status.eq(status) .and(minOrderCount != null ? JPAExpressions.select(qOrder.count()) .from(qOrder) .where(qOrder.userId.eq(qUser.id)) .goe(minOrderCount) : null)) .fetch();

虽然代码量相近，但后者完全避免了SQL字符串拼接，所有逻辑都在Java类型系统保护下。

3. SpringBoot项目迁移实战

3.1 环境准备

在pom.xml中添加依赖：

<dependency> <groupId>com.querydsl</groupId> <artifactId>querydsl-apt</artifactId> <scope>provided</scope> </dependency> <dependency> <groupId>com.querydsl</groupId> <artifactId>querydsl-jpa</artifactId> </dependency> <build> <plugins> <plugin> <groupId>com.mysema.maven</groupId> <artifactId>apt-maven-plugin</artifactId> <version>1.1.3</version> <executions> <execution> <phase>generate-sources</phase> <goals> <goal>process</goal> </goals> <configuration> <outputDirectory>target/generated-sources/querydsl</outputDirectory> <processor>com.querydsl.apt.jpa.JPAAnnotationProcessor</processor> </configuration> </execution> </executions> </plugin> </plugins> </build>

3.2 查询工厂配置

创建JPAQueryFactory的Spring配置：

@Configuration public class QueryDslConfig { @Bean public JPAQueryFactory jpaQueryFactory(EntityManager em) { return new JPAQueryFactory(em); } }

3.3 渐进式迁移策略

我们采用"新老并存"的迁移方案：

1. 并行运行阶段（1-2周）

   • 新功能直接使用QueryDSL实现
   • 旧功能保持MP不变
   • 通过集成测试保证两者结果一致

2. 逐步替换阶段（2-3周）

   • 按模块逐个替换MP实现
   • 每次替换后运行全量回归测试

3. 完全迁移阶段

   • 移除MyBatis相关依赖
   • 清理废弃的XML映射文件

4. 高级查询模式详解

4.1 动态条件构建

使用BooleanBuilder处理复杂条件组合：

public List<Order> findOrders(OrderSearchCondition condition) { QOrder qOrder = QOrder.order; BooleanBuilder builder = new BooleanBuilder(); if (condition.getStartDate() != null) { builder.and(qOrder.createTime.goe(condition.getStartDate())); } if (condition.getEndDate() != null) { builder.and(qOrder.createTime.loe(condition.getEndDate())); } // 嵌套条件 if (condition.getKeywords() != null) { BooleanBuilder keywordBuilder = new BooleanBuilder(); for (String keyword : condition.getKeywords()) { keywordBuilder.or(qOrder.description.contains(keyword)); } builder.and(keywordBuilder); } return queryFactory.selectFrom(qOrder) .where(builder) .fetch(); }

4.2 自定义结果映射

将查询结果映射到DTO的几种方式：

方案1：使用Projections.constructor

List<OrderDTO> dtos = queryFactory.select( Projections.constructor(OrderDTO.class, qOrder.id, qOrder.orderNo, qUser.name.as("userName"))) .from(qOrder) .join(qUser).on(qOrder.userId.eq(qUser.id)) .fetch();

方案2：使用Tuple+Stream转换

List<OrderDTO> dtos = queryFactory.select( qOrder.id, qOrder.orderNo, qUser.name) .from(qOrder) .join(qUser).on(qOrder.userId.eq(qUser.id)) .fetch() .stream() .map(tuple -> new OrderDTO( tuple.get(qOrder.id), tuple.get(qOrder.orderNo), tuple.get(qUser.name))) .collect(Collectors.toList());

4.3 分页查询优化

QueryDSL的分页查询会智能生成count语句：

public Page<Order> pageOrders(Pageable pageable) { JPAQuery<Order> query = queryFactory.selectFrom(qOrder) .orderBy(qOrder.createTime.desc()); long total = query.fetchCount(); List<Order> content = query .offset(pageable.getOffset()) .limit(pageable.getPageSize()) .fetch(); return new PageImpl<>(content, pageable, total); }

注意：对于大数据量表，建议重写count查询以避免全表扫描

5. 性能调优与陷阱规避

5.1 N+1查询问题

警惕关联查询导致的性能问题：

// 错误示例：会导致N+1查询 List<Order> orders = queryFactory.selectFrom(qOrder) .join(qOrder.items).fetchJoin() // 必须显式声明fetchJoin .fetch();

5.2 查询日志监控

配置logback.xml输出SQL日志：

<logger name="org.hibernate.SQL" level="DEBUG"/> <logger name="org.hibernate.type.descriptor.sql.BasicBinder" level="TRACE"/>

5.3 缓存策略

二级缓存配置示例：

@Entity @Cacheable @org.hibernate.annotations.Cache( usage = CacheConcurrencyStrategy.READ_WRITE) public class Product { // ... }

6. 企业级实践建议

6.1 代码组织规范

推荐的项目结构：

src/main/java ├── com │ └── example │ ├── config │ ├── controller │ ├── model │ │ ├── entity │ │ └── qmodel # 存放生成的Q类 │ ├── repository │ │ ├── custom # 自定义查询接口 │ │ └── impl # 查询实现 │ ├── service │ └── dto

6.2 事务管理要点

@Service @RequiredArgsConstructor public class OrderService { private final JPAQueryFactory queryFactory; @Transactional public void updateOrderStatus(Long orderId, Status newStatus) { queryFactory.update(qOrder) .set(qOrder.status, newStatus) .where(qOrder.id.eq(orderId)) .execute(); } }

重要：更新操作必须添加@Transactional注解

7. 迁移后的效果评估

经过三个月的生产环境验证，我们观察到以下改进：

最令人惊喜的是团队开发体验的改善。新加入的工程师能在两天内上手复杂查询开发，而之前需要至少一周的MyBatis学习曲线。