MyBatis-Plus Wrapper链式查询条件使用指南

MyBatis-Plus 的 Wrapper 链式查询看似简洁优雅，实则暗藏多重陷阱：因采用不可变设计，每次调用 eq、like 等方法均返回新实例，若未链式承接或重新赋值，条件将悄然丢失；字符串式 QueryWrapper 易引发字段名重构失败与运行时异常，而 LambdaQueryWrapper 虽提升类型安全与 IDE 支持，却对 null 引用敏感且不支持动态字段；复杂 or/and 嵌套需精准控制括号层级，误用会导致 SQL 逻辑彻底偏离预期；更隐蔽的是空条件默认生成 “WHERE 1=1”，极易触发全表扫描引发线上慢查——掌握引用管理、空值防护、括号封装和条件校验四大关键，才能让链式调用真正可靠高效。

Wrapper 链式调用为什么拼着拼着就失效了

因为 Wrapper 的大多数方法（如 eq()、like()、in()）返回的是新实例，不是原对象——它内部是不可变设计。你以为在“往同一个对象上加条件”，其实每次都在生成新对象，旧引用早就断了。

• 错误写法：QueryWrapper w = new QueryWrapper(); w.eq("age", 18); userMapper.selectList(w); → 这里 eq() 返回了新 QueryWrapper，但你没接住，w 还是空的
• 正确写法：必须链式或赋值，比如 userMapper.selectList(new QueryWrapper().eq("age", 18).like("name", "张"))
• 如果中间要分支判断，别用临时变量覆盖原引用，改用 apply() 或提前构造好再传入，或者用 LambdaQueryWrapper 配合 if 块内直接调用

LambdaQueryWrapper 比 QueryWrapper 少踩一半坑

QueryWrapper 用字符串写字段名，编译不检查，重构时字段一改就报 org.apache.ibatis.reflection.ReflectionException；LambdaQueryWrapper 用方法引用来指定字段，IDE 能跳转、能重命名、编译期报错。

• 安全写法：new LambdaQueryWrapper().eq(User::getAge, 25).like(User::getName, "李")
• 注意：不能对 null 字段引用，比如 User::getDeleted 如果是布尔包装类且可能为 null，eq() 会抛 NPE；建议先判空，或用 isNull()/isNotNull()
• 不支持动态表名或字段名——Lambda 形式锁死了实体类结构，想运行时拼字段？只能退回 QueryWrapper + 字符串，但得自己兜底校验

多个 or 条件嵌套时，and 和 or 的优先级怎么控制

MyBatis-Plus 的 or() 默认是和上一级同级的 or，不是括号内的 or。想表达 (a=1 AND (b=2 OR c=3))，必须显式用 and() + or() 函数式写法包裹。

• 错误理解：w.eq("a", 1).and(i -> i.eq("b", 2).or().eq("c", 3)) → 这个 or() 是和 eq("b", 2) 并列，实际生成 a=1 AND (b=2 OR c=3)，是对的
• 但写成 w.eq("a", 1).eq("b", 2).or().eq("c", 3) 就变成 (a=1 AND b=2) OR c=3，容易误读
• 真正需要多层括号时，用 and() 接一个 Consumer，里面再嵌 or()，例如：and(q -> q.eq("x", 1).or(r -> r.like("y", "a").like("z", "b")))

Wrapper 传参为空时怎么避免查出全表

用户没输任何搜索条件，你却执行了 select * from user where 1=1 —— 这是 QueryWrapper 默认行为，也是线上慢查询常见源头。

• 最简单防御：在 service 层加空校验，if (wrapper.getExpression() == null) { throw new IllegalArgumentException("查询条件不能为空"); }
• 更稳妥做法：用 EmptyWrapper 替代默认空 Wrapper，或者初始化时就设 last("LIMIT 0")，等条件补全再用 clear() 清掉
• 注意 lambdaQuery().eq(null, null) 不会报错，但会生成 WHERE column IS NULL，如果字段不允许 null，这条件永远不命中——看着像没查，实则全表扫描后无结果

Wrapper 的链式调用看着流畅，但每个点都是引用切换；字段写错、空值处理、括号层级、空条件放行——四点里漏一个，查出来的数据就不是你要的。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《MyBatis-Plus Wrapper链式查询条件使用指南》文章吧，也可关注golang学习网公众号了解相关技术文章。