MyBatis-Plus自定义SQL实战：XML映射与Wrapper结合应对复杂查询

1. 项目概述：为什么我们需要自定义SQL？

在项目里用MyBatis-Plus（后面简称MP）的朋友，估计都享受过它带来的便利：单表CRUD基本不用写SQL，一个LambdaQueryWrapper就能搞定大部分查询。但干过几个真实项目你就会发现，现实远比理想骨感。我见过不少团队，项目初期图快，所有查询都硬套MP的Wrapper，结果遇到多表关联、复杂子查询、数据库特定函数（比如Oracle的LISTAGG或者MySQL的窗口函数）时，代码就变得又臭又长，性能还上不去。最后要么在Wrapper里拼接一堆apply和last，要么干脆绕开MP，直接回MyBatis的老路写XML。

所以，“实现自定义SQL”这个事，绝不是为了炫技。它的核心价值在于平衡：在享受MP自动化单表操作便利性的同时，为复杂业务场景保留最灵活、最直接的SQL控制权。这就像给你的工具箱里既配了电动螺丝刀（MP的Wrapper），也留了一把精密的瑞士军刀（自定义SQL）。什么时候该用哪把工具，考验的就是我们对框架的理解和项目边界的把控。

最近社区里关于MP的讨论，比如“分页查询怎么配”、“若依框架怎么集成MP”，背后其实都指向同一个问题：当标准方案不够用时，我们如何优雅地扩展？今天，我就结合自己踩过的坑，把MP里玩转自定义SQL的几种主流姿势、各自的适用场景以及那些官方文档里没明说的细节，给你一次讲透。

2. 核心思路：MP自定义SQL的三种武器库

实现自定义SQL，MP其实给了我们三条清晰度不同的路径。选哪条路，取决于你对“自定义”程度的要求以及团队的技术习惯。

2.1 武器一：Wrapper +@Select注解（轻度自定义）

这是最轻量、最快速的方式，适合在简单的多条件查询中，嵌入一小段固定的SQL片段。

核心逻辑：利用QueryWrapper生成大部分WHERE条件，对于Wrapper无法表达的复杂部分（如一个特定的函数或子查询），通过@Select注解直接在Mapper接口方法上写完整SQL，并将Wrapper作为参数传入。MP会智能地将Wrapper生成的条件拼接到你的SQL中。

实操示例：假设我们要查询用户列表，但有一个特殊条件：只筛选出积分（points）大于所在部门平均积分的用户。这个“大于部门平均分”的条件，用Lambda表达式很难直接写。

// 1. 在UserMapper接口中定义方法 public interface UserMapper extends BaseMapper<User> { @Select("SELECT u.* FROM user u ${ew.customSqlSegment}") List<User> selectUsersWithComplexCondition(@Param(Constants.WRAPPER) Wrapper<User> wrapper); } // 2. 在Service或Controller中构造Wrapper并调用 public void queryUsers() { QueryWrapper<User> wrapper = new QueryWrapper<>(); // 可以添加Wrapper能处理的常规条件 wrapper.like("name", "张") .eq("status", 1); // 关键：使用 `apply` 方法注入自定义的SQL片段 // 注意：`apply` 内的片段会直接拼接，需注意SQL注入和安全 wrapper.apply("u.points > (SELECT AVG(points) FROM user WHERE dept_id = u.dept_id)"); // 调用自定义方法 List<User> userList = userMapper.selectUsersWithComplexCondition(wrapper); }

为什么这么用？这里的${ew.customSqlSegment}是MP提供的占位符，它会被替换成Wrapper生成的WHERE关键字及其后的条件语句。apply方法里的字符串则会原样拼接到WHERE条件中。这种方式下，你只定义了SELECT ... FROM部分，WHERE条件由你和Wrapper共同动态生成。

注意事项：

1. SQL注入风险：apply方法直接拼接字符串，如果前端参数未经严格过滤就传入apply，风险极高。绝对不要写成wrapper.apply(“points > “ + userInput)。对于动态值，应使用{0}占位符，并通过apply的重载方法传入参数：

wrapper.apply(“date_column > {0}”, someDate);

2. 表别名：在@Select注解的SQL中，如果涉及多表或子查询，最好显式使用表别名（如示例中的u），并在apply的片段中也使用相同的别名，确保SQL语法正确。
3. 适用场景局限：这种方式最适合在WHERE条件中插入固定或相对简单的自定义片段。对于整个SQL语句结构都复杂的情况（如多层嵌套子查询、UNION查询），就显得力不从心了。

2.2 武器二：XML映射文件（中度到重度自定义）

这是MyBatis的“正统”，也是MP完全兼容的“大杀器”。当你需要编写完整的、复杂的SQL语句时，XML映射文件提供了最强大的能力和最清晰的SQL与Java代码的分离。

核心逻辑：将SQL写在独立的Mapper.xml文件中，MP的BaseMapper接口及其方法会自动与之关联。你可以在XML中编写任意复杂度的SQL，并利用MyBatis强大的动态SQL标签（<if>,<choose>,<foreach>等）来构建灵活的逻辑。

实操示例：实现一个分页的多表关联查询，查询用户信息及其部门名称，并且支持根据多个动态条件筛选。

<!-- UserMapper.xml --> <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd"> <mapper namespace="com.example.mapper.UserMapper"> <!-- 自定义结果映射，关联查询必备 --> <resultMap id="UserDeptResultMap" type="com.example.entity.User"> <id property="id" column="id"/> <result property="name" column="name"/> <result property="email" column="email"/> <result property="deptId" column="dept_id"/> <!-- 关联部门信息 --> <association property="department" javaType="com.example.entity.Department"> <id property="id" column="dept_id"/> <result property="deptName" column="dept_name"/> </association> </resultMap> <!-- 自定义分页查询SQL --> <select id="selectUserPageWithDept" resultMap="UserDeptResultMap"> SELECT u.id, u.name, u.email, u.dept_id, d.id as dept_id, d.name as dept_name FROM user u LEFT JOIN department d ON u.dept_id = d.id <where> <!-- 动态条件：姓名模糊查询 --> <if test="query.name != null and query.name != ''"> AND u.name LIKE CONCAT('%', #{query.name}, '%') </if> <!-- 动态条件：部门ID精确匹配 --> <if test="query.deptId != null"> AND u.dept_id = #{query.deptId} </if> <!-- 动态条件：状态多选 --> <if test="query.statusList != null and query.statusList.size() > 0"> AND u.status IN <foreach collection="query.statusList" item="status" open="(" separator="," close=")"> #{status} </foreach> </if> <!-- 甚至可以嵌入复杂的子查询 --> <if test="query.minPoints != null"> AND u.points > (SELECT AVG(points) FROM user WHERE dept_id = u.dept_id) </if> </where> ORDER BY u.create_time DESC </select> </mapper>

对应的Mapper接口和Service：

// UserMapper.java public interface UserMapper extends BaseMapper<User> { // 方法名与XML中的id对应 IPage<UserDeptVO> selectUserPageWithDept(Page<User> page, @Param(“query”) UserQueryDTO query); } // Service层调用 public IPage<UserDeptVO> getUserPage(Page<User> page, UserQueryDTO query) { return userMapper.selectUserPageWithDept(page, query); }

为什么这是最推荐的方式？

1. 关注点分离：SQL集中在XML里，Java代码干净，便于DBA或后端开发者单独Review和优化SQL。
2. 功能强大：可以利用MyBatis全部的动态SQL能力，处理极其复杂的条件分支和循环。
3. 易于调试：可以直接在数据库客户端测试写好的SQL，再粘贴到XML中。
4. 天然防注入：所有参数都通过#{}占位符绑定，安全无忧。

实操心得：

1. XML文件位置：确保你的Mapper.xml文件放在resources目录下对应的包路径中（如resources/com/example/mapper/），并与Mapper接口的包名一致。这是MyBatis的默认扫描约定，在Spring Boot中通常无需额外配置。
2. 分页插件配置：要使自定义XML分页查询生效，必须在Spring Boot配置类中配置MP的分页插件。这是很多新手会掉的坑。

@Configuration public class MybatisPlusConfig { @Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); // 添加分页插件 interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); // 根据数据库类型调整 return interceptor; } }

3. 参数传递：XML中通过@Param注解指定的名称（如“query”）来引用参数。对于复杂对象，使用query.propertyName的方式访问其属性。

2.3 武器三：自定义SQL注入器（深度定制，高阶玩法）

这是MP最灵活、也最复杂的扩展方式。它允许你完全定义一个新的Mapper方法，并为其注入自定义的SQL执行逻辑。当你需要创造一种MP本身不支持的通用操作模式时（比如批量Upsert、逻辑删除的扩展行为），就需要用到它。

核心逻辑：通过实现com.baomidou.mybatisplus.core.injector.ISqlInjector接口或继承AbstractSqlInjector类，向MP的Mapper中注入全新的方法。你需要自己编写该方法的SQL模板和运行时逻辑。

适用场景：比如，MP默认提供的insert是单条插入，虽然也有insertBatch，但某些数据库（如MySQL）的批量插入语法有优化空间。我们可以注入一个更高效的批量插入方法。

由于实现一个完整的SQL注入器步骤较多，这里概述其关键步骤：

1. 定义自定义方法接口：创建一个接口，声明你的新方法。
2. 编写SQL模板：创建一个类，继承AbstractMethod，在injectMappedStatement方法中定义SQL语句。
3. 创建SQL注入器：创建一个类，继承DefaultSqlInjector，重写getMethodList方法，将你的自定义方法添加到方法列表中。
4. 注册注入器：将你的SQL注入器配置为Spring Bean，替换MP默认的注入器。

为什么用这种方式？它实现了框架级别的复用。一旦配置好，所有Mapper都能使用这个新方法，就像使用MP自带的selectById一样自然。但这属于框架底层扩展，除非有强烈的、通用的定制需求，否则不建议轻易使用，因为维护成本较高。

3. 实战精讲：XML方式实现分页联表查询

让我们聚焦于最常用、也最强大的XML方式，通过一个完整的实战案例，把每一步的细节和坑点都捋清楚。这个案例将覆盖：多表关联、动态条件、分页查询、结果集映射（ResultMap）以及排序。

3.1 环境准备与依赖确认

首先，确保你的pom.xml依赖正确。以Spring Boot 2.7.x 和 MyBatis-Plus 3.5.17为例（这也是当前社区搜索的热点版本）：

<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.7.18</version> <!-- 与MP 3.5.17兼容性较好的版本 --> </parent> <dependencies> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-boot-starter</artifactId> <version>3.5.17</version> </dependency> <dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <scope>runtime</scope> </dependency> <!-- 其他依赖... --> </dependencies>

版本匹配要点：MP 3.5.x 与 Spring Boot 2.7.x 是黄金搭档。如果你用的是Spring Boot 3.x，则需要使用MP的更高版本（如5.x）。社区里“mybatis-plus version3.5.17对应的springboot版本”的疑问，答案就是Spring Boot 2.7.x系列。

3.2 定义查询参数DTO与返回VO

清晰的参数和返回对象是写好复杂查询的第一步。避免直接在Controller层用Map接收参数或在SQL里用Object。

// 查询参数DTO @Data public class UserQueryDTO { private String name; // 用户名模糊查询 private Long deptId; // 部门ID精确匹配 private List<Integer> statusList; // 状态多选 private Integer minPoints; // 最低积分 // 可以加入分页参数，但更推荐用Page对象单独传递 } // 返回结果VO (View Object) @Data public class UserDeptVO { private Long id; private String name; private String email; private Long deptId; // 关联的部门信息 private String deptName; // 其他需要返回的字段... }

为什么用VO而不是Entity？实体类（Entity）User通常与数据库user表严格对应。而联表查询的结果，字段可能来自多张表（如dept_name）。用一个专门的VO来接收，语义更清晰，也避免了给实体类增加不属于它本身业务的属性，保持实体类的纯净。

3.3 编写Mapper接口与XML映射文件

Mapper接口：

public interface UserMapper extends BaseMapper<User> { /** * 分页查询用户及其部门信息 * @param page 分页参数对象，MP会自动处理 * @param query 查询条件对象 * @return 分页结果 */ IPage<UserDeptVO> selectUserPageWithDept(@Param(“page”) Page<User> page, @Param(“query”) UserQueryDTO query); }

注意：这里返回类型是IPage<UserDeptVO>，泛型是VO，不是Entity。@Param注解至关重要，它定义了参数在XML中的名称。

XML映射文件 (UserMapper.xml)： 关键点在于<resultMap>的定义和动态SQL<where>标签的使用。

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd"> <mapper namespace="com.example.mapper.UserMapper"> <!-- 重点1：定义结果映射 --> <resultMap id="UserDeptVOResultMap" type="com.example.vo.UserDeptVO"> <id property="id" column="id"/> <result property="name" column="user_name"/> <!-- 注意字段别名 --> <result property="email" column="email"/> <result property="deptId" column="dept_id"/> <result property="deptName" column="dept_name"/> </resultMap> <!-- 重点2：编写包含动态条件的完整SQL --> <select id="selectUserPageWithDept" resultMap="UserDeptVOResultMap"> SELECT u.id, u.name as user_name, <!-- 使用别名避免字段名冲突或歧义 --> u.email, u.dept_id, d.name as dept_name FROM user u LEFT JOIN department d ON u.dept_id = d.id <where> <!-- 使用 <if> 标签实现动态条件 --> <if test="query.name != null and query.name.trim() != ''"> AND u.name LIKE CONCAT('%', #{query.name}, '%') </if> <if test="query.deptId != null"> AND u.dept_id = #{query.deptId} </if> <if test="query.statusList != null and query.statusList.size() > 0"> AND u.status IN <foreach collection="query.statusList" item="status" open="(" separator="," close=")"> #{status} </foreach> </if> <!-- 一个相对复杂的子查询条件示例 --> <if test="query.minPoints != null"> AND u.points >= #{query.minPoints} </if> <!-- 可以继续添加其他条件 --> </where> <!-- 排序 --> ORDER BY u.create_time DESC </select> </mapper>

关键细节解析：

1. <resultMap>：它是连接SQL结果集和Java VO对象的桥梁。column属性对应SQL查询结果的列名（或别名），property对应VO对象的属性名。当数据库字段名（如u.name）与VO属性名（name）不一致，或者存在多表同名字段时，必须使用别名并在resultMap中明确指定。例如，上例中将u.name别名为了user_name，并在resultMap中映射到name属性。
2. <where>标签：这个标签非常智能。它会自动处理WHERE关键字，并且去掉开头多余的AND或OR。如果<where>标签内所有<if>条件都不成立，它会自动省略整个WHERE子句，避免SQL语法错误。
3. <foreach>标签：处理IN查询的利器。collection指定集合参数名，item是遍历的每个元素的变量名，open和close是包装括号，separator是元素间的分隔符。
4. 参数访问：在<if>的test表达式或#{}占位符中，使用query.xxx的格式来访问UserQueryDTO对象的属性。@Param(“query”)注解让query这个名称在XML中可用。

3.4 Service层与Controller层调用

Service层：

@Service public class UserServiceImpl extends ServiceImpl<UserMapper, User> implements UserService { @Override public IPage<UserDeptVO> getUserPage(Page<User> page, UserQueryDTO queryDTO) { // 直接调用自定义的Mapper方法 return baseMapper.selectUserPageWithDept(page, queryDTO); } }

这里baseMapper是MP在ServiceImpl中为我们注入的当前实体对应的Mapper（即UserMapper），可以直接使用其所有方法，包括我们自定义的。

Controller层：

@RestController @RequestMapping(“/user”) public class UserController { @Autowired private UserService userService; @GetMapping(“/page”) public R<IPage<UserDeptVO>> getUserPage( @RequestParam(defaultValue = “1”) long current, @RequestParam(defaultValue = “10”) long size, UserQueryDTO queryDTO) { // 查询条件对象 // 构建MP的分页对象 Page<User> page = new Page<>(current, size); // 调用Service IPage<UserDeptVO> result = userService.getUserPage(page, queryDTO); return R.ok(result); } }

MP的Page对象包含了当前页码、每页大小、排序信息等。它作为参数传入后，MP的分页插件会拦截查询，自动计算总记录数并执行分页逻辑，最终IPage对象里会包含分页数据（records）和分页信息（total,size,current等）。

4. 避坑指南与性能优化

在实际使用中，尤其是从纯MyBatis迁移过来或在复杂场景下，会遇到一些典型问题。

4.1 分页插件失效与总数为-1的问题

问题描述：调用自定义的XML分页查询方法后，返回的IPage对象中，分页数据正确，但total（总记录数）为0或-1。

根本原因：MP的分页插件是通过拦截器（PaginationInnerInterceptor）实现的。它会在执行你的查询SQL前，自动生成一条COUNT(*)语句来查询总数。如果插件没有正确配置或没有生效，就不会执行这一步。

解决方案：

1. 确认插件已配置：如2.2节所述，必须在配置类中声明MybatisPlusInterceptor并添加PaginationInnerInterceptor。
2. 检查SQL兼容性：分页插件会自动优化COUNT语句。但对于极其复杂的SQL（如带有WITH子句的公共表表达式、UNION等），插件可能无法正确解析。此时，你需要自定义count查询。
   • 方法一：在XML中单独提供一个count查询（推荐）。

     <select id=“selectUserPageWithDeptCount” resultType=“java.lang.Long”> SELECT COUNT(*) FROM user u LEFT JOIN department d ON u.dept_id = d.id <!-- 这里需要复制与主查询完全一致的WHERE条件 --> <where> <if test=“query.name != null and query.name.trim() != ‘’“> AND u.name LIKE CONCAT(‘%’, #{query.name}, ‘%’) </if> <!-- ... 其他条件 ... --> </where> </select>

     然后在Mapper接口中增加一个返回Long的selectUserPageWithDeptCount方法，并使用@Param(“query”)。MP插件会优先使用这个自定义的count方法。
   • 方法二：在Page对象中设置不优化count语句（简单但可能影响性能）。

     Page<User> page = new Page<>(current, size); page.setOptimizeCountSql(false); // 关闭自动优化

4.2 字段映射失败与别名使用

问题描述：查询结果中，某些字段（尤其是VO中新增的或来自关联表的字段）值为null。

排查步骤：

1. 检查resultMap：确认<result>标签的property和column是否一一对应，特别是大小写。数据库字段名通常是下划线风格（dept_name），Java属性是驼峰风格（deptName）。MP默认开启了驼峰映射，但如果你的字段别名不是标准下划线，或者resultMap中明确指定了column，则以resultMap为准。
2. 检查SQL中的别名：在多表关联查询时，如果两张表有同名字段（如user表和department表都有name字段），必须在SELECT语句中为它们起不同的别名，并在resultMap中引用这些别名。这是最常见的错误来源。
3. 开启MyBatis日志：在application.yml中设置日志级别，查看最终执行的SQL语句和返回的结果集字段名，这是最直接的调试手段。

   logging: level: com.example.mapper: debug # 将你的Mapper包路径设置为debug

4.3 动态SQL条件中的空字符串与集合判断

在<if>标签的test表达式中，判断字符串为空和判断集合为空有细微差别。

• test=“query.name != null and query.name != ‘’“：这是标准写法，判断不为null且不是空字符串。
• test=“query.name != null and query.name.trim() != ‘’“：更严谨，先去除首尾空格再判断，避免用户输入一堆空格导致条件失效。
• 判断集合：test=“query.statusList != null and query.statusList.size() > 0“。也可以使用MyBatis内置的_parameter关键字或@Param注解的名称，但直接使用参数名更直观。

4.4 性能考量：N+1查询问题

在定义<resultMap>时，除了<association>（一对一），还有<collection>（一对多）。警惕在<collection>中嵌套过深的查询，这可能导致著名的“N+1查询”问题（主查询1次，获取N条主记录，然后每条主记录再执行一次子查询）。

优化建议：

1. 尽量使用单次联表查询：就像我们上面的例子，通过JOIN一次性将主表和关联表的数据查出来，通过结果映射（resultMap）组装对象。这是最高效的方式。
2. 如果关联数据过多或过于复杂：考虑拆分成两次查询。第一次查询主列表（分页），第二次根据主列表的ID集合，批量查询关联数据，然后在内存中（Service层）进行组装。这通常比在SQL中多层嵌套JOIN或触发N+1查询要快。
3. 使用MP的@TableField注解进行关联查询：对于简单的一对一关联，MP支持在实体类中使用@TableField的select属性指定一个子查询，但这本质上仍然是N+1，不推荐在列表查询中使用。

5. 进阶：在若依等现有框架中集成MP自定义SQL

社区里很多朋友在问“若依框架不分离版4.8.3版本 想将mybatis 改为mybatis-plus”。对于若依这类已经成熟的框架，集成MP并启用自定义SQL，需要系统性地替换。

核心步骤：

1. 替换依赖：在pom.xml中，将mybatis-spring-boot-starter依赖替换为mybatis-plus-boot-starter。
2. 修改配置：将application.yml中所有mybatis开头的配置项改为mybatis-plus开头。例如mybatis.mapper-locations改为mybatis-plus.mapper-locations。MP完全兼容MyBatis的配置。
3. 修改基类：若依的BaseEntity、BaseMapper、BaseService、BaseServiceImpl等需要调整。让BaseMapper继承MP的BaseMapper，让BaseServiceImpl继承MP的ServiceImpl。这是一个细致活，需要对照MP的API修改方法签名和实现。
4. 处理XML：原有的MyBatis XML映射文件绝大部分可以直接使用，因为MP 100%兼容MyBatis。只需注意，如果原来XML里用了${}进行字符串拼接（有注入风险），建议借机改为安全的#{}绑定。
5. 添加分页插件：这是必须的！在若依的配置类（如RuoYiConfig）或新建一个配置类中，添加MybatisPlusInterceptor和PaginationInnerInterceptor的Bean定义。
6. 逐步重构：不要试图一次性重写所有DAO方法。可以先从简单的单表查询开始，用MP的Wrapper替换原有的Example或XML中的简单语句。对于复杂的多表查询，保留原有XML方式，这正是“自定义SQL”的价值所在。

这个过程的关键是平滑迁移，保证原有功能不受影响。自定义SQL（XML）能力的存在，使得你可以先完成框架替换，再逐步优化具体的SQL实现，风险可控。

自定义SQL不是MP的短板，反而是它设计哲学中“强大且灵活”的体现。它没有试图用一个Wrapper封装所有SQL场景，而是明智地选择了“放手”，将复杂场景交还给最专业的MyBatis XML去处理。掌握好这几种自定义方式，尤其是XML映射文件，你就能在项目里真正做到游刃有余，既享受了MP的便捷，也不失应对复杂业务的底气。