MyBatis Plus动态SQL：${ew.sqlSegment}与${ew.customSqlSegment}深度解析与实战避坑指南
在MyBatis Plus的日常开发中，动态SQL的灵活运用能显著提升开发效率。但许多开发者在处理复杂查询条件时，常常对${ew.sqlSegment}和${ew.customSqlSegment}这两个看似相似的占位符感到困惑。它们虽然只有一词之差，但在实际使用中却有着截然不同的行为表现和适用场景。本文将深入剖析两者的核心差异，并通过典型错误案例和最佳实践，帮助开发者彻底掌握它们的正确用法。
1. 核心概念解析：从Wrapper到SQL片段
1.1 Wrapper条件构造器基础
MyBatis Plus的Wrapper体系是动态SQL的核心组件，它通过链式API让开发者能够以面向对象的方式构建查询条件。常见的实现类包括：
QueryWrapper：用于SELECT查询条件构造UpdateWrapper：用于UPDATE操作条件构造LambdaQueryWrapper：类型安全的Lambda表达式写法
// 典型Wrapper使用示例 QueryWrapper<User> wrapper = new QueryWrapper<>(); wrapper.eq("status", 1) .like("username", "admin") .between("create_time", startDate, endDate);1.2 SQL片段生成机制
当Wrapper对象被传递到Mapper方法时，MyBatis Plus会将其转换为实际的SQL片段。这里就涉及到两种不同的转换方式：
| 占位符类型 | 生成内容 | 包含WHERE关键字 |
|---|---|---|
${ew.sqlSegment} | 仅条件表达式部分 | 否 |
${ew.customSqlSegment} | 完整WHERE子句（含WHERE关键字） | 是 |
关键差异：${ew.customSqlSegment}会在生成的SQL中自动包含WHERE关键字，而${ew.sqlSegment}仅输出条件表达式部分。
2. 典型错误场景与语法陷阱
2.1 错误用法：WHERE关键字重复
最常见的错误是在已经使用<where>标签的情况下，又错误地选择了${ew.customSqlSegment}：
<!-- 错误示例：将导致SQL语法错误 --> <select id="selectList" resultType="User"> SELECT * FROM user <where> ${ew.customSqlSegment} <!-- 实际生成：WHERE deleted=0 AND WHERE username='admin' --> </where> </select>执行时将抛出SQL语法异常，因为生成了重复的WHERE关键字。
2.2 条件丢失问题
另一个极端是过度使用${ew.sqlSegment}而忽略了必要的固定条件：
<!-- 不完善的示例 --> <select id="selectList" resultType="User"> SELECT * FROM user WHERE deleted = 0 <!-- 固定条件 --> ${ew.sqlSegment} <!-- 如果wrapper为空，将导致语法错误 --> </select>当Wrapper没有添加任何条件时，最终的SQL会变成WHERE deleted = 0，末尾可能残留多余的AND。
3. 正确使用模式与最佳实践
3.1 与<where>标签的完美配合
MyBatis的<where>标签能自动处理前缀AND/OR和空条件情况，与${ew.sqlSegment}是黄金组合：
<!-- 正确示例 --> <select id="selectList" resultType="User"> SELECT * FROM user <where> deleted = 0 <if test="ew != null and ew.sqlSegment != null"> AND ${ew.sqlSegment} </if> </where> </select>这种写法能确保：
- 无论Wrapper是否有条件，基础查询都能正常工作
- 不会出现WHERE关键字重复
- 自动处理条件间的AND连接
3.2 动态排序与复杂子查询
对于需要动态排序或包含复杂子查询的场景，推荐使用@Select注解配合Wrapper：
@Select("SELECT * FROM user ${ew.customSqlSegment}") List<User> selectAll(@Param(Constants.WRAPPER) Wrapper<User> wrapper);此时使用${ew.customSqlSegment}是合适的，因为：
- 整个SQL片段由Wrapper完全控制
- 可以包含ORDER BY等完整子句
- 适用于需要完全自定义SQL结构的场景
4. 高级应用场景与性能优化
4.1 多表关联查询处理
在复杂的多表查询中，合理组合使用两种占位符：
<select id="selectUserWithRole" resultMap="userRoleMap"> SELECT u.*, r.role_name FROM user u LEFT JOIN user_role ur ON u.id = ur.user_id LEFT JOIN role r ON ur.role_id = r.id <where> u.deleted = 0 AND r.deleted = 0 <if test="ew != null and ew.sqlSegment != null"> AND ${ew.sqlSegment} </if> </where> </select>4.2 性能优化注意事项
索引命中：确保Wrapper生成的条件能利用到表索引
// 好的实践：使用索引字段 wrapper.eq("username", "admin").eq("status", 1); // 避免：使用未索引的字段作为主要条件 wrapper.like("description", "重要");参数绑定：MyBatis Plus自动使用预编译参数，防止SQL注入
/* 实际执行的SQL */ WHERE username = ? AND status = ? /* 安全 */批量操作：对于IN查询，建议拆分为多个批次处理
// 分批处理大型IN查询 List<List<Long>> batches = Lists.partition(idList, 1000); batches.forEach(batch -> { wrapper.clear(); wrapper.in("id", batch); mapper.selectList(wrapper); });
5. 实战决策树与代码模板
5.1 选择占位符的决策流程
是否需要完整WHERE子句？ ├── 是 → 使用${ew.customSqlSegment} │ └── 适用场景： │ - 整个WHERE子句由Wrapper完全控制 │ - 需要包含ORDER BY等额外子句 └── 否 → 使用${ew.sqlSegment} └── 适用场景： - 需要与其他固定条件组合 - 使用<where>标签管理条件逻辑5.2 安全使用模板代码
XML Mapper模板：
<select id="selectByWrapper" resultType="YourEntity"> SELECT * FROM your_table <where> <!-- 固定条件 --> deleted = 0 <!-- 动态条件 --> <if test="ew != null and ew.sqlSegment != null"> AND ${ew.sqlSegment} </if> </where> <!-- 固定排序 --> ORDER BY create_time DESC </select>Java调用示例：
public PageInfo<YourEntity> queryByCondition(QueryCondition cond, PageParam page) { QueryWrapper<YourEntity> wrapper = new QueryWrapper<>(); // 构建动态条件 wrapper.eq(cond.getType() != null, "type", cond.getType()) .like(StringUtils.isNotBlank(cond.getKeyword()), "name", cond.getKeyword()); // 分页查询 Page<YourEntity> pageObj = new Page<>(page.getPageNum(), page.getPageSize()); return PageHelper.startPage(pageObj) .doSelectPageInfo(() -> mapper.selectByWrapper(wrapper)); }在实际项目中，我发现很多团队会自定义基础Mapper模板，将${ew.sqlSegment}的标准用法封装到基类中。这种模式既保证了统一性，又能避免每个Mapper都重复处理Wrapper逻辑。一个实用的技巧是在Wrapper构建时添加entity参数，可以自动忽略null值的字段：
QueryWrapper<User> wrapper = new QueryWrapper<>(user); // 自动忽略user中为null的字段
