MyBatis-Plus复杂查询与自定义SQL实战指南

1. MyBatis-Plus 自定义 SQL 与复杂查询概述MyBatis-Plus 作为 MyBatis 的增强工具在简化 CRUD 操作的同时也提供了强大的条件构造器和自定义 SQL 能力。在实际项目中我们经常会遇到需要执行复杂查询的场景这时候就需要灵活运用 MyBatis-Plus 提供的各种查询构建方法。我曾在多个电商项目中处理过复杂的商品查询需求比如多条件筛选、动态排序、分组统计等。这些场景下MyBatis-Plus 的条件构造器Wrapper和自定义 SQL 功能发挥了巨大作用。下面我将分享这些实战经验帮助你掌握 MyBatis-Plus 的复杂查询技巧。2. 条件构造器的核心用法2.1 基础条件构建MyBatis-Plus 提供了多种条件构造器最常用的是 QueryWrapper 和 LambdaQueryWrapper。LambdaQueryWrapper 通过方法引用来指定字段避免了硬编码字段名是更推荐的方式。// 创建 LambdaQueryWrapper LambdaQueryWrapperUser wrapper new LambdaQueryWrapper(); // 等于条件 wrapper.eq(User::getName, 张三); // 大于条件 wrapper.gt(User::getAge, 18); // 模糊查询 wrapper.like(User::getEmail, example.com); // 范围查询 wrapper.between(User::getCreateTime, startDate, endDate);在实际项目中我建议优先使用 LambdaQueryWrapper因为它有以下优势类型安全编译时就能发现字段名错误重构友好字段名修改会自动更新代码更简洁可读性更好2.2 复杂条件组合对于更复杂的查询条件我们可以使用 and 和 or 方法来组合条件LambdaQueryWrapperUser wrapper new LambdaQueryWrapper(); wrapper.eq(User::getStatus, 1) .and(w - w.gt(User::getAge, 18).or().eq(User::getVipLevel, 3));对应的 SQL 是SELECT * FROM user WHERE status 1 AND (age 18 OR vip_level 3)在电商项目中这种组合条件非常常见比如查询上架状态且(价格低于100或销量大于1000)的商品。2.3 动态条件构建实际项目中查询条件往往是动态的。MyBatis-Plus 的条件方法都提供了带 condition 参数的重载public ListUser queryUsers(String name, Integer minAge) { LambdaQueryWrapperUser wrapper new LambdaQueryWrapper(); wrapper.eq(StringUtils.isNotBlank(name), User::getName, name) .gt(minAge ! null, User::getAge, minAge); return userMapper.selectList(wrapper); }这种写法可以避免在代码中写大量的 if 判断使代码更加简洁。我在处理后台管理系统中的筛选功能时这种动态条件构建方式特别有用。3. 自定义 SQL 实现复杂查询3.1 XML 方式自定义 SQL当内置的条件构造器无法满足需求时我们可以使用 MyBatis 原生的 XML 方式定义 SQL!-- UserMapper.xml -- select idselectComplexUsers resultTypeUser SELECT u.* FROM user u LEFT JOIN department d ON u.dept_id d.id WHERE u.status #{status} if testdeptName ! null AND d.name LIKE CONCAT(%, #{deptName}, %) /if ORDER BY u.create_time DESC /select然后在 Mapper 接口中定义对应方法public interface UserMapper extends BaseMapperUser { ListUser selectComplexUsers(Param(status) Integer status, Param(deptName) String deptName); }这种方式适合特别复杂的 SQL特别是涉及多表关联、复杂计算或数据库特定函数的场景。3.2 注解方式自定义 SQL对于简单的自定义 SQL可以使用注解方式Select(SELECT * FROM user WHERE age #{age} ORDER BY ${sortField} ${sortOrder}) ListUser selectByAgeWithSort(Param(age) int age, Param(sortField) String sortField, Param(sortOrder) String sortOrder);注意使用 ${} 时要特别注意 SQL 注入风险确保参数值可信。我建议只在排序字段等场景使用 ${}其他情况都用 #{}。3.3 条件构造器与自定义 SQL 结合MyBatis-Plus 支持在自定义 SQL 中使用条件构造器生成的 WHERE 条件Select(SELECT * FROM user ${ew.customSqlSegment}) ListUser selectAll(Param(Constants.WRAPPER) WrapperUser wrapper);这样可以在保留条件构造器便利性的同时自定义 SELECT 部分。我在分页查询时经常使用这种方式Select(SELECT u.*, d.name as dept_name FROM user u LEFT JOIN department d ON u.dept_id d.id ${ew.customSqlSegment}) ListUser selectUserWithDept(Param(Constants.WRAPPER) WrapperUser wrapper);4. 高级查询技巧与实战经验4.1 子查询处理MyBatis-Plus 提供了多种子查询支持// 使用 inSql 进行子查询 wrapper.inSql(User::getDeptId, SELECT id FROM department WHERE status 1); // 使用 exists wrapper.exists(SELECT 1 FROM user_role ur WHERE ur.user_id user.id AND ur.role_id 1);在权限系统中我常用 exists 子查询来过滤有特定权限的用户。4.2 分组与聚合查询虽然 MyBatis-Plus 主要面向单表 CRUD但也可以处理分组查询QueryWrapperUser wrapper new QueryWrapper(); wrapper.select(dept_id, COUNT(*) as user_count, AVG(age) as avg_age) .groupBy(dept_id) .orderByDesc(user_count); ListMapString, Object result userMapper.selectMaps(wrapper);对于复杂的统计报表我通常会创建专门的统计方法而不是直接使用条件构造器。4.3 联表查询优化MyBatis-Plus 本身不直接支持联表查询但可以通过以下方式实现使用自定义 SQL推荐使用 TableField 注解处理关联字段使用 MyBatis 的 association 和 collection在用户-部门关联查询场景我的做法是Data public class UserVO { private Long id; private String name; private Integer age; TableField(exist false) private String deptName; } // Mapper 方法 Select(SELECT u.*, d.name as dept_name FROM user u LEFT JOIN department d ON u.dept_id d.id ${ew.customSqlSegment}) ListUserVO selectUserVO(Param(Constants.WRAPPER) WrapperUser wrapper);4.4 分页查询实践MyBatis-Plus 的分页功能非常强大// 创建分页对象 PageUser page new Page(1, 10); // 构建查询条件 LambdaQueryWrapperUser wrapper new LambdaQueryWrapper(); wrapper.eq(User::getStatus, 1) .orderByDesc(User::getCreateTime); // 执行分页查询 PageUser result userMapper.selectPage(page, wrapper); // 获取分页数据 ListUser records result.getRecords(); long total result.getTotal();对于自定义 SQL 的分页查询Select(SELECT u.*, d.name as dept_name FROM user u LEFT JOIN department d ON u.dept_id d.id ${ew.customSqlSegment}) PageUserVO selectUserVOPage(PageUser page, Param(Constants.WRAPPER) WrapperUser wrapper);5. 性能优化与常见问题5.1 索引命中优化使用条件构造器时要注意索引命中// 好的写法 - 能命中 name 索引 wrapper.eq(User::getName, 张三); // 不好的写法 - 无法命中索引 wrapper.likeLeft(User::getName, 三); // 好的模糊查询写法 - 能命中右模糊索引 wrapper.likeRight(User::getName, 张);在实际项目中我建议避免在索引字段上使用左模糊避免对索引字段使用函数操作复合索引要注意字段顺序5.2 N1 问题解决在关联查询中容易出现 N1 问题。解决方案包括使用 JOIN 一次性获取所有数据使用 MyBatis 的延迟加载在 Service 层手动处理关联数据我通常采用第一种方式因为它最简单高效Select(SELECT u.*, d.name as dept_name FROM user u LEFT JOIN department d ON u.dept_id d.id WHERE u.id #{id}) UserVO selectUserWithDept(Long id);5.3 动态表名处理在多租户系统中经常需要动态表名。MyBatis-Plus 提供了多种解决方案使用 SQL 注入器使用动态表名处理器在自定义 SQL 中使用变量我的实践是使用动态表名处理器public class MyTableNameHandler implements TableNameHandler { Override public String dynamicTableName(String sql, String tableName) { return tableName _ TenantContext.getCurrentTenant(); } }然后在配置中启用Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); DynamicTableNameInnerInterceptor dynamicTableNameInnerInterceptor new DynamicTableNameInnerInterceptor(); dynamicTableNameInnerInterceptor.setTableNameHandler(new MyTableNameHandler()); interceptor.addInnerInterceptor(dynamicTableNameInnerInterceptor); return interceptor; }5.4 常见问题排查条件不生效问题检查是否使用了正确的条件构造器特别是 LambdaQueryWrapper 和 QueryWrapper 的区别SQL 注入风险避免直接拼接 SQL特别是使用 ${} 和 SelectProvider 时要小心性能问题使用 MyBatis-Plus 的 SQL 分析插件来监控慢查询分页总数不准复杂 SQL 可能需要自定义 count 查询6. 实际项目案例分享6.1 电商商品多条件筛选在电商项目中商品筛选是非常复杂的。以下是一个简化版的实现public PageProductVO searchProducts(ProductQuery query, PageProduct page) { LambdaQueryWrapperProduct wrapper new LambdaQueryWrapper(); // 基础条件 wrapper.eq(Product::getStatus, ProductStatus.ON_SHELF) .eq(query.getCategoryId() ! null, Product::getCategoryId, query.getCategoryId()) .like(StringUtils.isNotBlank(query.getKeyword()), Product::getName, query.getKeyword()); // 价格区间 wrapper.between(query.getMinPrice() ! null query.getMaxPrice() ! null, Product::getPrice, query.getMinPrice(), query.getMaxPrice()); // 排序处理 if (price.equals(query.getSortField())) { wrapper.orderByAsc(price.equals(query.getSortField()), Product::getPrice); } else if (sales.equals(query.getSortField())) { wrapper.orderByDesc(sales.equals(query.getSortField()), Product::getSales); } else { wrapper.orderByDesc(Product::getCreateTime); } // 执行查询 PageProduct productPage productMapper.selectPage(page, wrapper); // 转换为VO return productPage.convert(this::convertToVO); }6.2 权限系统中的动态数据过滤在权限系统中我们经常需要根据用户角色动态过滤数据public ListOrder getUserOrders(Long userId) { LambdaQueryWrapperOrder wrapper new LambdaQueryWrapper(); // 普通用户只能看自己的订单 if (!currentUser.isAdmin()) { wrapper.eq(Order::getUserId, userId); } // 部门管理员可以看到本部门所有订单 if (currentUser.isDeptAdmin()) { wrapper.or().inSql(Order::getUserId, SELECT user_id FROM user_dept WHERE dept_id currentUser.getDeptId()); } return orderMapper.selectList(wrapper); }6.3 报表统计查询对于复杂的统计报表我通常会创建专门的统计方法Select(SELECT DATE_FORMAT(create_time, %Y-%m-%d) as day, COUNT(*) as total, SUM(amount) as amount FROM orders WHERE create_time BETWEEN #{start} AND #{end} GROUP BY DATE_FORMAT(create_time, %Y-%m-%d)) ListOrderStats getDailyStats(Param(start) Date start, Param(end) Date end);7. 最佳实践与建议经过多个项目的实践我总结了以下 MyBatis-Plus 复杂查询的最佳实践合理选择查询方式简单查询使用条件构造器中等复杂度条件构造器 自定义 SELECT高度复杂完全自定义 SQL保持代码可读性长条件链适当换行复杂条件提取为方法添加必要的注释性能注意事项避免在循环中查询数据库大数据量查询考虑分页合理使用缓存测试建议测试各种边界条件验证生成的 SQL监控生产环境查询性能团队协作规范统一使用 LambdaQueryWrapper复杂 SQL 添加注释说明共享常用查询工具类最后记住 MyBatis-Plus 只是工具要根据实际项目需求选择合适的用法不要为了用而用。在特别复杂的业务场景下有时候直接使用 MyBatis 或 JPA 可能更合适。