MyBatis-Plus分页插件SQL报错：COUNT()为空根源与修复方案-代码聚汇网

MyBatis-Plus分页插件SQL报错：COUNT()为空根源与修复方案

芙蓉塘外有轻雷·2026-09-04·阅读 22 GEO检测（免费）

MyBatis-Plus分页插件COUNT()为空BadSqlGrammarException

|难度：普通|阅读约 47 分钟

1. 先从一次真实的翻车经历说起

项目用的是若依框架做的二开，MyBatis-Plus 做 ORM，多模块 Maven 工程，封装好了一个公共的 BaseService，里面统一处理分页查询逻辑。项目上了 Lombok，开发期一直跑得好好的，结果到了联调阶段，其他模块同事调我这个公共查询接口，日志里连续滚出一长串异常：

code复制org.springframework.jdbc.BadSqlGrammarException: 
### Error querying database.  Cause: java.sql.SQLSyntaxErrorException: 
You have an error in your SQL syntax; 
check the manual that corresponds to your MySQL server version for the right syntax to use near 'COUNT()' at line 1
### The error occurred while executing a query.
### Cause: java.sql.SQLSyntaxErrorException: 
You have an error in your SQL syntax; 
check the manual that corresponds to your MySQL server version

看到"BadSqlGrammarException"很自然地想到 SQL 语法不对，但当时最让人困惑的是 SQL 里的 SELECT COUNT() 根本没有字段名。MyBatis-Plus 自带的物理分页插件，理论上会自动完成 COUNT 包裹，为什么生成的 SQL 里会出现一个残缺的 COUNT()？

这类问题定位起来不复杂，但坑是真的多。我把当天排查的过程、底层原理、几种可能的触发场景以及最终修复方案完整记录下来，给后面遇到同样报错的同学一个参考。特别是如果你也是基于若依这种多模块封装了公共 Service 的结构，那这篇文章应该能帮你少走不少弯路。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 这个报错为什么会发生

2.1 分页插件在底层做了什么

MyBatis-Plus 的 PaginationInnerInterceptor 能帮开发者在执行分页时，自动拼接 LIMIT 语句，同时在查询总数时执行一条 COUNT 语句。正常场景下，我们调用 Page 对象后，框架会对原始 SQL 做一次内层包裹，类似：

sql复制SELECT COUNT(*) AS total FROM (原始SQL)

或者是直接把原 SQL 的主查询替换为 COUNT 聚合查询：

sql复制SELECT COUNT(*) FROM user WHERE ...

如果你用了 Page 对象传入 Mapper 方法，日志里会在正式查询数据之前，先打印一条 ==> Preparing: SELECT COUNT(*) AS total FROM ...，然后再执行真正的分页查询。

报错信息里的 COUNT() 括号里是空的，这显然不是框架默认逻辑生成的。框架默认逻辑不会故意生成一个没有参数的 COUNT，能导致它出现空括号，往往是因为开发者自己写了什么东西，让 SQL 解析器在拼接时裁剪出了问题，或者是原始 SQL 根本就不是一条标准可解析的查询语句。

2.2 最容易撞上的两类触发点

我当天排查的第一反应是检查自定义 SQL。项目里确实有一个统计用户自定义分组数量的方法，用了 ${} 拼接参数。${} 在 MyBatis 里是字符串直接替换，如果传入参数是一个子查询片段，可能拼进去之后 SQL 结构发生了变形。

当时日志里的完整 SQL 被打印出来后，我看到的是这么个形态：

sql复制SELECT COUNT() FROM (
    SELECT * FROM user WHERE name IN (...)
) total

这里的 COUNT() 空括号说明 MyBatis-Plus 在尝试对原 SQL 做 COUNT 改写时，没有成功识别出主表或者是原有的 SELECT 子句被某些注解干扰了。顺着这个思路，第二个点就是 Mapper 注解里的写法问题。

比如有人会在 Mapper 接口上写这种 SQL：

java复制@Select("<script>" +
        "SELECT ${selectColumns} FROM user " +
        "WHERE status = #{status}" +
        "</script>")
List<User> selectUserList(@Param("selectColumns") String columns, 
                          @Param("status") Integer status);

selectColumns 如果传的是 *，在分页插件做 count 优化的时候，生成的 SQL 就可能出现异常。MyBatis-Plus 对这类"嵌入式字段"的解析能力有限，它会尝试通过数据库元数据去兜底，但兜底失败后就只能生成空的 COUNT 表达式。

2.3 根本原因归纳

从底层机制来看，BadSqlGrammarException: SELECT COUNT() 的原因可以浓缩成一句话：MyBatis-Plus 在执行 COUNT 优化时，试图从原始 SQL 中提取需要计数的目标，但由于 SQL 的动态片段存在无法预知的形态，最终生成的 COUNT 表达式不合法。

常见的触发场景包括：

原 SQL 使用了 ${} 直接拼接 SQL 片段，且拼接内容是一条完整的子查询或视图逻辑。
Mapper 方法注解里写的是动态 SQL，字段列表来自外部传入，分页插件没法正确解析。
多表 join 查询时把 group by 写在了一个特殊位置，导致 COUNT 改写时被去掉 SELECT 字段而产生空括号。
另一种隐藏情况：方法返回值类型和 Mapper 泛型不匹配，分页插件在走 countOptimize 时拿不到 JParser 需要的表信息。

其实这几种情况背后有一个共性：凡是破坏了 SQL 语义的可静态分析结构的写法，都有可能让分页插件的智能改写失效。

3. 分步排查的过程还原

3.1 第一步：打开 SQL 日志，确认生成的真实语句

在排查之前先做一件事：确认项目配置里打印了完整 SQL。如果你还没打印 SQL，可以临时改一下 application.yml：

yaml复制mybatis-plus:
  configuration:
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

这样 MyBatis 会把预编译语句和参数都打印在控制台。日志非常关键，因为业务代码里写的 Mapper 方法 SQL 并不等于最终执行的 SQL。分页插件会拦截后做改写，错误往往发生在改写环节。

我的日志里看到 executor 先执行了一个错误的分页 COUNT，其中的 SQL 片段确实不是自己写的。原业务方法是这样的：

java复制@Select("SELECT ${ew.sqlSegment} FROM user")
List<User> selectBySegment(@Param(Constants.WRAPPER) Wrapper<User> wrapper);

业务侧调用的时候通过 QueryWrapper 传入了一个带子查询的条件：

java复制wrapper.inSql("id", "SELECT user_id FROM user_group WHERE group_name = 'VIP'");

当 QueryWrapper 里的 inSql 片段经过分页插件解析时，插件尝试把 select 字段裁剪掉并生成 count SQL，它的简化逻辑是把第一个 selectItem 替换成 COUNT(*)，但 inSql 子查询的存在导致整个 WHERE 块被当成字段级内容处理，最后生成的 SQL 变成了空 COUNT。

3.2 第二步：判断是 COUNT 优化造成了问题，还是 SQL 本身就有语法错误

看到报错后，先不要动业务代码，直接拿日志里完整的 SQL 去数据库客户端执行。如果原始 SQL（去掉 count 包裹之前能执行的语句）是正常的，说明问题出在分页插件改写阶段，跟本身业务 SQL 无关。

如果直接执行原始 SQL 都报错，那问题在 SQL 本身，比如多个 join 条件写错、参数没替换、表名写错等。

实际排查时，日志只会打印最终执行 SQL。很多同学遇到 BadSqlGrammarException 后会很困惑，因为日志里的 SQL 被打印出来是拼接后的完整 SQL，表面看起来没什么毛病，但把它放进数据库去执行却报语法错误。这就是因为 MyBatis-Plus 的执行日志和数据库实际解析的 SQL 在个别高版本 MySQL 驱动下有格式或字符集的差异，不过大部分情况是一致的。

遇到这种情况，我建议的方式是打开 MyBatis-Plus 分页插件内置的 count 优化开关看能否把问题定位出来：

java复制PaginationInnerInterceptor paginationInterceptor = new PaginationInnerInterceptor(DbType.MYSQL);
paginationInterceptor.setOptimizeJoin(false);

optimizeJoin 默认是 true，它会对 join 查询做 COUNT 改写优化。如果改写成 false，则走"全包一层子查询"的路子，这种方案虽然性能不一定最优，但正确性最为稳妥。这也是经验之一：遇到分页 COUNT 解析异常时，先关闭 join 优化试试。

3.3 第三步：从小白视角复现并排除多模块与 Lombok 的干扰

既然项目是多模块结构，并且引入了 Lombok，要留意两个方向的干扰：

Lombok 在编译期会生成 Getter/Setter、Builder 等方法。如果实体类里某个字段的 Getter 方法和 SQL 映射产生混淆，运行时反射得到的属性会和预期不符。有一种很隐蔽的情况是：实体类手动写了一个 getTotalCount() 方法，同时加上了 @TableField(exist = false)，但 Lombok 的 @Data 又自动生成了类似的方法，存在重复方法或字段映射异常。虽然这种情况一般不直接导致空 COUNT，但容易让人走偏。

多模块环境下更容易犯的错误是：公共模块里的 Mapper 和实体类被打包成 jar 后，另一模块扫描 Mapper XML 会因为路径不一致导致 XML 缺失，进而用注解 SQL 或兜底 SQL 代替预期 SQL。我们这次的问题出在公共 BaseService 的泛型定义和实际实体不一致，导致分页插件在处理时需要根据实体类推断表名，推断失败后 COUNT 的列名丢失。

排查多模块问题一定要在启动参数里加上扫描日志或者使用 Actuator 的 Mappings 端点，确认每一个 Mapper 接口都被正确注册到了当前 Spring 容器。如果注册映射不完整，行为会非常诡异。

4. 定位根因与修复方案

4.1 针对空 COUNT 的三种修复思路

经过日志验证和插件开关切换测试后，定位到问题真正出现在一条继承自公共 BaseMapper 的统计 SQL 上。核心代码类似：

java复制public interface UserGroupMapper extends BaseMapper<UserGroup> {
    
    @Select("SELECT user_id, count(group_id) AS group_cnt " +
            "FROM user_group " +
            "WHERE group_name IN (${groupNames}) " +
            "GROUP BY user_id")
    List<Map<String, Object>> countGroupByNames(@Param("groupNames") String groupNames);
}

调用时用 Page 参数做分页，MyBatis-Plus 对包含 GROUP BY 的 SQL 进行 COUNT 改写时，是有可能把 select 字段裁剪掉后用 COUNT(DISTINCT group by 字段) 去处理的。同时原始 SQL 里拼接了 ${groupNames}，由于字符串格式问题，最终 SQL 里 groupNames 被替换后产生了空字符串，导致引擎在内部做 count 优化的时候发现 select 列表是空的，于是输出 SELECT COUNT()。

修复方式有三种，根据实际情况选：

方案一：把 ${} 拼接改成 #{} 或循环标签

尽量避免 ${} 拼字符串。如果需要 IN 集合，就传 List<String>，用 MyBatis 的 foreach：

xml复制SELECT user_id, COUNT(group_id) AS group_cnt
FROM user_group
WHERE group_name IN
<foreach collection="groupNames" item="item" open="(" separator="," close=")">
    #{item}
</foreach>
GROUP BY user_id

对于分页查询，如果 SQL 是 XML 里写死的，MyBatis-Plus 可以安全改写。传参进 foreach 是标准做法，不会破坏分页插件的解析。

方案二：牺牲一点性能，让分页插件走保守模式

关闭首页 count 的 join 优化，或者干脆使用自定义 count SQL。

MyBatis-Plus 里支持在分页对象 Page 上设置一个自定义 countId，通过 Page.setCountId() 或者是 Mapper 接口方法上使用 @Options 之类的方式（具体要看版本），让分页插件不去解析原始 SQL，而是去执行你预先写好的 count 语句。这种方式对复杂报表 SQL 特别实用，因为一旦 SQL 复杂到 JSqlParser 解析不动，直接手工维护一条 count 反而最省心。

java复制Page<UserGroup> page = new Page<>(1, 10);
page.setCountId("userGroupCount"); // 对应 XML 里一条自定义 count SQL 的 id

方案三：分页 COUNT 关掉自动优化

分页查询总数对于大表来说是刚需，但某些实时性要求不高的统计场景，其实可以用 Page 对象里的 setSearchCount(false) 来跳过 COUNT，只查询数据总量估算值或者做滚动加载。不适用时也建议调整 SQL 写法，拆分出独立的 count 与 page 查询，放弃 MyBatis-Plus 自动 count 能力。

4.2 修复后的细节与验证

我最终采用方案一的做法，把公共统计方法里的 ${groupNames} 全部改成 XML 里的 foreach 写法。修改后分页插件自动生成的 COUNT SQL 是：

sql复制SELECT COUNT(*) FROM user_group WHERE group_name IN (?, ?, ?)

日志里这条 SQL 正常执行。随后数据列表 SQL 也正常执行，加了 LIMIT ?,参数也都正确。

在修复过程中注意了一个很关键的点：如果原始 Mapper 方法返回 List<Map<String, Object>>，且传入 Page 做了分页，那么 Mapper 方法泛型拿不到实体类型时，MyBatis-Plus 的分页插件是无法安全地生成 COUNT 语句的。我后来在需要分页的统计场景都改成了自定义实体，比如：

java复制public interface UserGroupMapper {
    IPage<GroupCountVO> selectGroupCountPage(Page<?> page, @Param("groupNames") List<String> groupNames);
}

XML 里不拼接任何动态片段，只做参数绑定。这样分页插件的解析成功率最高，泛型也稳定，不会再出现空 COUNT。

4.3 顺手说下若依框架下最容易踩到的坑

如果是若依框架，比较典型的是它自带的 BaseController 里封装了 startPage() 方法，底层通过 PageHelper 的 ThreadLocal 来做分页。很多人项目既引入了 MyBatis-Plus 又保留了若依自带的 PageHelper 依赖，这两个框架在同一个项目里会互相干扰。

MyBatis-Plus 的分页插件是一个 MyBatis 拦截器，PageHelper 也是拦截器。当两条链路同时存在时，如果代码里先调用了若依的 startPage()，又调用了 MyBatis-Plus 的 Page 对象去查询，那底层的拦截器顺序会导致 SQL 拼接异常。有些项目还不报错，只是分页数据不对；有些直接就出现 SQL 语法错误。遇到诡异的 BadSqlGrammarException 时，可以先看看项目依赖里是否有 pagehelper-spring-boot-starter 和 mybatis-plus-boot-starter 并存。

解决方案是在若依二开项目里统一移除 PageHelper，只保留一个分页实现，或者在引入依赖时排除掉。从我个人经验看，如果主体用了 MyBatis-Plus，那么所有分页都应该走同一套 API，不要混用。

5. 完整的代码修复示例：从复现到验证

5.1 复现的工程条件

为了便于说明，我列一下复现环境：

Spring Boot 2.7.10
MyBatis-Plus 3.5.3.1
MySQL 8.0.28
多模块 Maven 工程，公共模块封装了 BaseMapper。
Lombok 一直开着，实体类基本都是 @Data。

核心 Mapper：

java复制public interface UserGroupMapper extends BaseMapper<UserGroup> {

    List<GroupCountVO> selectGroupCountPage(Page<GroupCountVO> page,
                                            @Param("groupNames") List<String> groupNames);
}

核心 XML：

xml复制<select id="selectGroupCountPage" resultType="com.example.vo.GroupCountVO">
    SELECT user_id,
           COUNT(group_id) AS group_cnt
    FROM user_group
    WHERE group_name IN
    <foreach collection="groupNames" item="item" open="(" separator="," close=")">
        #{item}
    </foreach>
    GROUP BY user_id
</select>

ServiceImpl 里：

java复制public IPage<GroupCountVO> pageGroupCount(List<String> groupNames, long current, long size) {
    Page<GroupCountVO> page = new Page<>(current, size);
    return userGroupMapper.selectGroupCountPage(page, groupNames);
}

这样写是完全没有问题的。MyBatis-Plus 生成的 count SQL 会是：

sql复制SELECT COUNT(*) FROM (
    SELECT user_id, COUNT(group_id) AS group_cnt
    FROM user_group
    WHERE group_name IN (?, ?, ?)
    GROUP BY user_id
) TOTAL

因为外层包了一层子查询，某些极端情况下这条 count SQL 依然是低效的，比如 group 的表数据量大，但如果总数本身就很大，这个代价可以接受。

5.2 自定义 count SQL 的完整实现方案

如果你更关心分页接口的响应时间，可以采用自定义 count 优化不精确统计的方案。

首先在 Mapper 接口里声明两个方法：

java复制IPage<GroupCountVO> selectGroupCountPage(Page<GroupCountVO> page,
                                         @Param("groupNames") List<String> groupNames);

Long selectGroupCount(@Param("groupNames") List<String> groupNames);

XML 中分别实现列表查询和 count 查询：

xml复制<select id="selectGroupCountPage" resultType="com.example.vo.GroupCountVO" countId="selectGroupCount">
    SELECT user_id, COUNT(group_id) AS group_cnt
    FROM user_group
    WHERE group_name IN
    <foreach collection="groupNames" item="item" open="(" separator="," close=")">
        #{item}
    </foreach>
    GROUP BY user_id
</select>

<select id="selectGroupCount" resultType="long">
    SELECT COUNT(DISTINCT user_id)
    FROM user_group
    WHERE group_name IN
    <foreach collection="groupNames" item="item" open="(" separator="," close=")">
        #{item}
    </foreach>
</select>

在 MyBatis-Plus 3.4.3 之后的版本里，可以通过 XML 标签 select 的 countId 属性指定 count 查询的 Mapper 方法 ID，让分页插件在查找总数时优先执行这条 SQL，而不是自己解析列表 SQL 生成 COUNT。该方案在 group by 复杂查询上的收益很明显，因为 list 可能 JOIN 了 5 张表，但 count 只需要从核心表里去重统计，性能差距有可能是几十倍的。

注意：countId 指定的方法必须和当前 select 在同一个 Mapper XML 命名空间下，且返回类型通常为 Long 或数字类型。如果主查询带了很重的查询条件，count 查询本身要确保条件与主查询完全一致，否则分页 total 会不准确，这种不一致很容易被忽略但危害比较大。

5.3 批量更新或插入场景中的分页坑

这个报错还有一个常见隐身版本，就是 Mapper 方法上标注了 @Param 但并未传入 Page 对象，此时 MyBatis-Plus 的分页插件不会触发分页逻辑，所以不会报分页错误。但如果你把一个 Page 对象塞进了 List<String> 类型的参数集合中，强行把它当作 IN 列表的一部分，SQL 在解析时也会出现奇怪的语法错误。例如：

java复制List<String> params = new ArrayList<>();
params.add("VIP");
params.add(page); // 错误，Page 对象被误当成了字符串

这种情况属于接口入参设计混乱，不如规规矩矩地把分页参数单独放出，不要塞进 params。

在批量 update 方法上误用 Page 也可能触发类似的 SQL 拼接错误，虽然 MyBatis-Plus 分页拦截器对 update 方法默认不拦截，但也有版本出现过对标注了特定注解方法做了错误处理。如果项目里有批量操作出现 BadSqlGrammarException，优先检查方法名是否匹配了拦截器的签名规则，比如方法名中包含 select 关键字，但实际是 update 语句，这样拦截器会误认为它是查询，进行奇怪的解析。

6. 分页慢如何结合 Redis 做优化

热搜词里有提到"分页查询慢怎么用 redis 优化"，这个和当前错误有一定关联。既然分页查询是常见性能瓶颈，我简单展开一下几种实际优化思路，但要注意优化并不能取代报错修复。

6.1 什么时候值得用缓存

分页 COUNT 慢的本质是要扫描大量数据做精确统计。比如一个千万级流水表，没有下推条件或者条件无法命中索引，每次 COUNT 都要全表扫描。这种场景下，如果接口对 total 精确值要求并不高，可以用缓存方案把 COUNT 结果缓存住，间隔 30 秒或 1 分钟刷新一次。前端分页组件里"总条数"显示略微延迟，基本无感知。

用 Redis 缓存方案一般是：

key 由分页查询条件拼接而成，比如 page:count:user_group:{groupNames的hash}。
缓存 value 保存 COUNT 总数和更新时间。
查询数据时，如果缓存里没有，则执行 COUNT 并写入缓存；有则在缓存有效期内直接读取缓存值，完整列表数据照常走数据库。

写成代码大致是：

java复制public IPage<GroupCountVO> pageGroupCountWithCache(List<String> groupNames, long current, long size) {
    String cacheKey = "page:count:group:" + DigestUtils.md5DigestAsHex(String.join(",", groupNames).getBytes(StandardCharsets.UTF_8));
    
    Page<GroupCountVO> page = new Page<>(current, size);
    Long total = redisTemplate.opsForValue().get(cacheKey);
    if (total == null) {
        IPage<GroupCountVO> result = userGroupMapper.selectGroupCountPage(page, groupNames);
        redisTemplate.opsForValue().set(cacheKey, result.getTotal(), 30, TimeUnit.SECONDS);
        return result;
    }
    page.setTotal(total);
    return userGroupMapper.selectGroupCountPage(page, groupNames);
}

这里要注意一个点：MyBatis-Plus 的 Page 对象在分页插件执行时才会把 total 值从 count SQL 里取出来并设置到 Page 对象上。如果你先手动 setTotal(total) 了，插件还是会执行 count SQL 并覆盖这个值。所以要么把 count SQL 优化掉，要么减少调用次数、单独用 Mapper 方法只查 list 不查 count。如果不用 searchCount = false，缓存 total 的做法在 MyBatis-Plus 默认分页流程里会被覆盖掉，这可能是很多想要自己优化的人没发现的一点。

6.2 实际业务中更实用的分页性能优化

真正的生产环境不推荐在业务代码里疯狂用 Redis 缓冲 count，因为分页条件组合如果非常多，缓存 key 会爆炸，维护成本极高。更靠谱的思路是这三条：

第一，从 DB 索引上下功夫。 查询条件涉及的字段尽量覆盖联合索引。MySQL 8.0 支持倒序索引，对于 ORDER BY create_time DESC LIMIT 10 这类查询帮助明显，可以在覆盖索引上保证排序和下推条件都走索引，避免 filesort。

第二，用"延迟关联"改写列表 SQL。 分页列表不要直接 JOIN 大表和大表，先查主表主键 ID 分页，再通过主键关联其他表补全字段。如：

sql复制SELECT u.*, o.order_cnt
FROM user u
LEFT JOIN order_stat o ON u.id = o.user_id
WHERE u.status = 1
ORDER BY u.create_time DESC
LIMIT 10, 10;

延迟关联改法是：

sql复制SELECT u.*, o.order_cnt
FROM (
    SELECT id FROM user
    WHERE status = 1
    ORDER BY create_time DESC
    LIMIT 10, 10
) tmp
JOIN user u ON tmp.id = u.id
LEFT JOIN order_stat o ON u.id = o.user_id;

子查询只查主键，再做关联，极大缩小了回表范围。这类改写对于深分页尤其有用，比如 LIMIT 100000, 10，不加延迟关联十条好等，加了之后勉强可接受。

第三，如果业务上允许，直接用"上一页最后一个 ID"替代 LIMIT 偏移量。 例如按 create_time 排序，把上一页最后一条记录的 create_time 和 id 作为查询条件传过来，SQL 变成：

sql复制WHERE (create_time < ? OR (create_time = ? AND id < ?))
ORDER BY create_time DESC
LIMIT 10

这种方案不适用于任意跳页，但无限滚动或"加载更多"场景用起来是性能最好的。对前端来说要改交互逻辑，所以得和产品谈好。

6.3 Redis 缓存踩坑提醒

用 Redis 优化 MyBatis-Plus 分页时，有几点必须注意：

不能缓存 Page 对象整体，因为里面还包含 records 数据，数据更新后缓存过期前会出现旧数据，和数据一致性冲突概率很大。当前只建议缓存 total。
缓存 key 别直接拼接超长字符串，先做 MD5，再做 key。如果你对 Redis key 的可读性有要求，可以用 hash field 存查询条件，key 存表名，避免长 key 占内存。
用了缓存之后依然要保留兜底逻辑。一旦 Redis 故障导致获取不到缓存值，最好有 switch 开关让流量直接打到 MySQL，保证核心链路不被缓存拖死。
如果用了 Spring Cache 的注解缓存整个查询结果，比如 @Cacheable(value = "userGroupPage", key = "#currentPage")，那就要注意缓存穿透，因为每一页都是一个缓存 key，如果用户频繁翻到空页，数据库压力反倒更大。

实际应用中最稳妥的 Redis 加分页策略是"只缓存聚合结果，不缓存列表明细"。明细数据的一致性很难保证，而 count 结果误差几十条通常在产品可接受范围内。

7. 排查这类 SQL 错误的通用方法清单

排查 BadSqlGrammarException 这类问题，建议按以下顺序走，每步都做记录：

第一步：打开 SQL 日志输出。 不开日志等于盲人摸象，先保证能看到最终拼接的 SQL 全文，同时把 mapper 接口方法名和 XML id 对应起来。

第二步：使用 show variables 等检查数据库版本。 有些 SQL 语法是 MySQL 5.7 和 8.0 之间的差异导致的，比如 WITH 子句、窗口函数、QUALIFY 等。MyBatis-Plus 高版本分页插件内部用了 JSqlParser，JSqlParser 对不同版本 MySQL 语法支持有细微差异。如果项目里用了窗口函数 ROW_NUMBER() OVER (...)，低版本的 JSqlParser 解析不出正确 SQL 时也会报异常，这个异常可能不是 BadSqlGrammarException 而是 JSQLParserException，但现象很相似，排错时也值得看一眼。

第三步：把日志中 SQL 单独放到数据库客户端里执行。 直接在客户端里跑，看数据库原始报错信息。Java 日志往往会把错误原因截断，数据库客户端报错往往更明确，会提示具体在哪个 token 附近出错。

第四步：检查 Mapper 接口泛型和 XML resultType。 泛型里如果是 Map，分页插件无法推断表结构，最好用 VO 类型替代。

第五步：检查 Wrapper 里是否有 select 字段为 null 的情况。 使用 QueryWrapper.select("") 空字符串可能会让 count 优化拿到空字段列表，进而生成空 COUNT。

第六步：检查是否引入了多个数据源插件或拦截器。 多数据源场景下，分页插件和动态数据源插件的执行顺序重要。如果在切换数据源后分页插件拿不到对应的 Dialect，直接用默认 MySQL 处理分页，也会出现异常。这里不是在说特定框架，只是提醒多数据源的通用风险。

第七步：如果你在 Spring Boot 项目里有多个自定义 MyBatis 拦截器，注意它们的执行顺序。 拦截器顺序不对会导致 SQL 被改写过早或过晚。比如有个自定义拦截器已经修改了 SQL 并加上了 LIMIT，MyBatis-Plus 分页插件又给加了一次 LIMIT，就会产生完全无法理解的 SQL。

8. 分页总条数如何快速验证是否正确

这个问题比较容易被忽略，修完报错后，很多同学的关注点在"不报错了"就完事了，没有仔细看总数是否正确。这里提一条快速验证路径：

写一个小的测试用例，控制入参返回确定结果集，比如 groupNames 传一个不存在的组名。
期望结果：total = 0，records 为空。
传一个只有 3 条记录的组名，size = 2，期望 current=1 返回 2 条记录，total=3。
手动调用 Mapper 的 count 方法，比对该 Mapper 列表查询通过 Page.getTotal() 得到的值，两者应该一致。

如果这两个值不一致，说明要么是 count SQL 写错了，要么是 MyBatis-Plus 自定义 count 没有和列表 SQL 使用一样的过滤条件。此类问题在代码中比较隐蔽，因为不会产生异常，但翻页后发现数据全乱了。使用 countId 自定义方案时特别容易出这种问题，比如列表 SQL 里有普通条件，count SQL 只拷贝了前半段，漏掉后面一个状态条件，总数会比实际大很多。

在 iframe 内嵌管理后台或者 APP 接口联调阶段，前端拿 total 来渲染分页组件，很容易发现这类不对，但很多人以为是前端 bug，白白浪费半天联调时间。

9. 如果项目里根本没有 XML，纯注解 SQL 该怎么处理

现在有些团队不写 XML，所有 SQL 都是注解写在 Mapper 接口上。遇到分页报错时处理方式稍有不同。

如果是注解 SQL，要分页尽量用 @Select + Page 参数的形式。但 XML 里能通过 countId 指定自定义 count，注解方式没有 XML nodes 概念，只能在接口方法上定义另一个方法来执行 count，然后手动改 Page 对象：

java复制IPage<UserGroup> selectPageByWrapper(Page<?> page, @Param(Constants.WRAPPER) Wrapper<UserGroup> wrapper);

这种方法的 count SQL 依然由分页插件自动生成。如果你有特别复杂的业务，注解 SQL 又要保证分页总数准确，强烈建议把 SQL 挪到 XML 里。注解 SQL 的掉坑点在于 SQL 字符串过长后很多断点难查，而且 MyBatis 注解里的 <script> 标签如果用错了位置，MyBatis-Plus 解析 SQL 的时候会把 script 标签当成普通文本传给数据库，这样数据库自然无法识别，报 SQL 语法错误。

对于纯注解项目的排查思路，除了开日志，多做一步：查看编译后 target/classes 目录下是否生成 Mapper XML。如果注解和 XML 同时存在，有的 MyBatis 版本会因为接口方法与 XML 中 id 重复导致绑定冲突，日志提示 BindingException 或者干脆使用 XML 的同名 SQL。这种冲突最致命的地方是你改注解 SQL 看似生效，其实底层用的还是 XML 里的旧 SQL，分页报的错误五花八门。

10. 我个人实测总结的语言与细节经验

最后补充一些非代码层面的排查经验，这类问题很多是工程结构导致的，不只是 SQL 写法：

第一，多模块项目排查时，先在发生报错的模块内做最小复现。 公共模块的 Service 代码大概率没问题，问题出在"调用端传入的 Wrapper 使用方式"和"子模块数据源配置"上。建议直接写一个 CommandLineRunner，固定参数调用 Mapper，快速定位是公共 Mapper 问题还是当前模块环境问题。

第二，Lombok 在复杂实体上要谨慎使用。 不是说 Lombok 本身会引发这个错误，而是如果实体类加了 @Accessors(chain = true) 然后又手动写了构建器，可能出现属性链式赋值导致的类型不匹配。加上 MyBatis-Plus 的实体扫描会把一些非表字段也纳入解析，若字段命名不规范，误伤概率就上来了。给字段都加上 @TableField(exist = false) 是个好习惯，这样可以明确告诉 MyBatis-Plus 哪些字段不入库不入查询。

第三，SQL 报错日志里的错误行号经常不准。 数据库报出的 line 1 不一定是你 SQL 的第一行有问题，可能是拼接后整体结构错位。所以不要只盯着行号看，要结合 SQL 的层次和括号配对去分析。自己写的 SQL 很简单时，可以复制到 notepad++ 或其他带括号匹配的工具里检查一下。

第四，升级依赖时要看分页插件对应的 JSqlParser 版本。 MyBatis-Plus 3.4.x 到 3.5.x 之间，内部对 group by 的处理逻辑就有变化。如果遇到旧代码以前不报错，升级后开始报 BadSqlGrammarException，那么很可能是因为新旧版本 JSqlParser 对数据库方言的解析规则不一样了。这种情况直接降级或者升级到目标版本后微调 SQL 是最快的。很多人不知道这个点，去改业务逻辑越改越乱，到头来发现是包版本问题。

我在这类问题上耗费了不少时间，相信这篇文章能帮后面的人清晰定位。SQL 报错本身不可怕，可怕的是排错路径不清晰，东试一下西试一下反而把问题搞复杂。把握住"读懂 SQL 日志、分清楚插件是否介入、不要让 SQL 变成不可静态分析的形式"这几点，大部分 MyBatis-Plus 分页异常都能快速解决。还是那句话，代码层面能做好的事，就不要丢给拦截器和框架去猜，去掉动态拼接和不可控变量，问题自然少一半。