QueryWrapper入门教程：从零开始构建MyBatis-Plus查询条件

一、引言：为什么需要QueryWrapper？

在传统MyBatis开发中，动态SQL拼接常依赖<if>标签或字符串拼接，这种方式在复杂查询场景下易导致代码冗余且难以维护。例如，一个包含多条件筛选、排序和分页的查询可能需要编写数十行XML配置或Java代码。MyBatis-Plus的QueryWrapper通过链式调用和条件构造器机制，将SQL条件构建过程转化为面向对象的编程模型，使开发者能用更简洁的代码实现复杂查询逻辑。

核心优势：

• 类型安全：避免字段名硬编码错误，重构时自动适配实体类变更

• 链式调用：通过方法链实现条件组合，代码可读性提升50%以上

• 动态条件：支持根据运行时参数决定是否添加查询条件

• SQL透明：自动生成标准SQL，减少手写SQL的调试成本

二、QueryWrapper基础概念

1. 条件构造器体系

MyBatis-Plus提供四类核心条件构造器，其继承关系如下：

选择建议：

• 查询操作优先使用LambdaQueryWrapper

• 更新操作优先使用LambdaUpdateWrapper

• 动态字段名场景（如字段名来自配置文件）使用QueryWrapper

2. 基本使用流程

// 1. 创建构造器实例
QueryWrapper<User> queryWrapper = new QueryWrapper<>();

// 2. 添加查询条件
queryWrapper.eq("status", 1) // WHERE status = 1
      .like("name", "张") // AND name LIKE '%张%'
      .orderByDesc("create_time"); // ORDER BY create_time DESC

// 3. 执行查询
List<User> users = userMapper.selectList(queryWrapper);

三、核心方法详解

1. 基础条件方法

动态条件示例：

String name = getRequestParam("name");
QueryWrapper<User> wrapper = new QueryWrapper<>();
wrapper.like(StringUtils.isNotBlank(name), "name", name) // 当name非空时添加条件
   .eq("status", 1);

2. 逻辑组合方法

复杂逻辑示例：

LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<>();
wrapper.eq(User::getStatus, "ACTIVE")
   .and(w -> w.gt(User::getAge, 18).or().isNotNull(User::getEmail))
   .orderByAsc(User::getAge);
// 生成SQL: 
// SELECT * FROM user 
// WHERE status = 'ACTIVE' 
// AND (age > 18 OR email IS NOT NULL) 
// ORDER BY age ASC

3. 查询扩展方法

字段选择优化：

// 避免SELECT *，减少网络传输
QueryWrapper<User> wrapper = new QueryWrapper<>();
wrapper.select("id", "name", "age", "email")
   .eq("status", 1);

四、LambdaQueryWrapper进阶用法

1. 方法引用优势

// 传统方式（字段名硬编码）
QueryWrapper<User> wrapper1 = new QueryWrapper<>();
wrapper1.eq("create_time", LocalDate.now());

// Lambda方式（编译期检查）
LambdaQueryWrapper<User> wrapper2 = new LambdaQueryWrapper<>();
wrapper2.eq(User::getCreateTime, LocalDate.now());

重构对比： 当实体类字段名从create_time改为gmt_create时：

• QueryWrapper需要手动修改所有字符串字段名

• LambdaQueryWrapper自动适配方法引用变更

2. 链式调用最佳实践

// 多条件组合示例
public List<User> findActiveUsers(Integer minAge, String keyword) {
  LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<>();
  wrapper.eq(User::getStatus, "ACTIVE")
     .ge(minAge != null, User::getAge, minAge) // 动态年龄条件
     .like(StringUtils.isNotBlank(keyword), User::getName, keyword) // 动态关键词
     .orderByDesc(User::getCreateTime);
  return userMapper.selectList(wrapper);
}

3. 嵌套条件实现

// 查询(年龄>30且性别为男) 或 (年龄<20且性别为女) 的用户
LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<>();
wrapper.nested(w -> w.gt(User::getAge, 30).eq(User::getGender, "M"))
   .or(w -> w.lt(User::getAge, 20).eq(User::getGender, "F"));
// 生成SQL:
// WHERE (age > 30 AND gender = 'M') OR (age < 20 AND gender = 'F')

五、实际应用场景解析

1. 动态搜索表单实现

public Page<User> searchUsers(UserSearchDTO searchDTO, PageParam pageParam) {
  LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<>();
  
  // 动态添加条件
  wrapper.eq(searchDTO.getStatus() != null, User::getStatus, searchDTO.getStatus())
     .like(StringUtils.isNotBlank(searchDTO.getName()), User::getName, searchDTO.getName())
     .between(searchDTO.getMinAge() != null && searchDTO.getMaxAge() != null, 
         User::getAge, 
         searchDTO.getMinAge(), 
         searchDTO.getMaxAge())
     .orderByDesc(searchDTO.getSortField(), User::getCreateTime); // 默认排序
  
  // 分页查询
  Page<User> page = new Page<>(pageParam.getPageNum(), pageParam.getPageSize());
  return userMapper.selectPage(page, wrapper);
}

2. 数据权限控制

// 根据当前用户角色添加数据权限条件
public List<Order> getUserOrders(Long userId, Set<String> roles) {
  LambdaQueryWrapper<Order> wrapper = new LambdaQueryWrapper<>();
  wrapper.eq(Order::getUserId, userId);
  
  // 管理员可查看所有订单
  if(!roles.contains("ADMIN")) {
    wrapper.eq(Order::getStatus, "PAID"); // 普通用户只能看已支付订单
  }
  
  return orderMapper.selectList(wrapper);
}

3. 复杂统计查询

// 统计各部门人数及平均年龄
public List<Map<String, Object>> getDepartmentStats() {
  QueryWrapper<User> wrapper = new QueryWrapper<>();
  wrapper.select("department", 
       "COUNT(*) as user_count", 
       "AVG(age) as avg_age")
     .groupBy("department");
  
  return userMapper.selectMaps(wrapper);
  // 返回示例: [{"department":"技术部","user_count":50,"avg_age":28.5}, ...]
}

六、性能优化建议

1. 索引优化

// 避免在非索引字段上使用函数
// 错误示例（导致索引失效）
QueryWrapper<User> badWrapper = new QueryWrapper<>();
badWrapper.apply("DATE_FORMAT(create_time,'%Y-%m') = {0}", "2025-07");

// 正确做法（使用范围查询）
QueryWrapper<User> goodWrapper = new QueryWrapper<>();
goodWrapper.between("create_time", 
          LocalDate.of(2025,7,1).atStartOfDay(),
          LocalDate.of(2025,7,31).atTime(23,59,59));

2. 批量查询优化

// 批量查询ID列表（推荐分批处理）
public void batchProcessUsers(List<Long> userIds) {
  // 每1000条分一批
  List<List<Long>> partitions = Lists.partition(userIds, 1000);
  
  partitions.forEach(partition -> {
    QueryWrapper<User> wrapper = new QueryWrapper<>();
    wrapper.in("id", partition);
    List<User> users = userMapper.selectList(wrapper);
    // 处理逻辑...
  });
}

3. 查询缓存策略

// 使用Spring Cache缓存查询结果
@Cacheable(value = "userCache", key = "#root.methodName + #searchDTO.toString()")
public Page<User> cachedSearchUsers(UserSearchDTO searchDTO, PageParam pageParam) {
  // 同上搜索实现
}

七、常见问题排查

1. 字段名不匹配错误

现象：Invalid bound statement (not found) 原因：

• 实体类字段与数据库列名未正确映射

• 使用LambdaQueryWrapper时实体类方法引用错误

解决方案：

// 实体类添加注解
@Data
@TableName("sys_user")
public class User {
  @TableField("user_name") // 指定数据库列名
  private String name;
}

// 查询时使用正确映射
LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<>();
wrapper.eq(User::getName, "张三"); // 自动映射到user_name列

2. 条件未生效问题

现象：生成的SQL缺少预期条件 排查步骤：

1. 检查条件方法的boolean参数是否正确

2. 使用wrapper.getLastSql()调试实际SQL

3. 确认条件方法的调用顺序（AND/OR优先级）

3. 分页失效问题

原因：

• 未配置分页插件

• 手动拼接SQL导致分页拦截失效

解决方案：

@Configuration
public class MybatisPlusConfig {
  @Bean
  public MybatisPlusInterceptor mybatisPlusInterceptor() {
    MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
    interceptor.addInnerInterceptor(new PaginationInnerInterceptor());
    return interceptor;
  }
}

八、总结与对比

1. 核心方法使用频率统计

2. 学习路径建议

1. 掌握LambdaQueryWrapper基础用法（2小时）

2. 实践动态条件组合（4小时）

3. 学习复杂查询场景实现（8小时）

4. 深入研究性能优化策略（持续）

通过系统学习QueryWrapper的条件构造机制，开发者可将SQL构建效率提升3-5倍，同时将条件相关bug率降低60%以上。建议从LambdaQueryWrapper入手，逐步掌握各类高级用法，最终形成适合自己的条件构造模式库。