PageHelper 分页陷阱：ThreadLocal 未清理引发的连锁异常

一、问题不是“偶发”，而是“必然等待被触发”

在很多后台管理系统的开发中，分页是一个再普通不过的功能。为了减少重复编写分页逻辑，开发者通常会引入成熟的分页辅助组件，通过“一行代码”完成分页参数注入与结果封装。这类组件虽然大幅提升了编码效率，但也隐藏着一个容易被忽视的陷阱：当分页状态被存放在线程局部变量中，却未能在业务执行结束后及时清理时，后续同一线程上执行的其他数据库操作就可能被“误伤”。

本文所讨论的问题，便来源于这样一类分页组件的典型实现。表面上看，系统只是在某些高并发场景下偶尔出现“注册用户已存在但仍能注册成功”“下拉列表只返回前几条数据”“修改密码偶尔报 SQL 语法错误”等诡异现象。由于异常并不稳定复现，排查难度通常较大。实际上，这些问题的共同根源往往是同一个：分页参数被错误地附加到了本不该分页的 SQL 语句上。

二、现象梳理：三个看似无关的故障

1. 已注册账号可以再次注册成功

用户注册接口中，通常会先调用用户名唯一性校验逻辑，再决定是否执行注册写入。其核心判断流程如下：

if (UserConstants.NOT_UNIQUE.equals(userService.checkUserNameUnique(username))
        || "匿名用户".equals(username)) {
    msg = "注册用户'" + username + "'失败";
}

其中，用户名唯一性校验对应的 SQL 可以简化为：

select count(1) from sys_user where user_name = #{userName} limit 1

按照正常逻辑，如果数据库中存在相同用户名，查询结果应为 1，接口会返回“注册用户失败”。但故障发生时，该查询却返回了 0，导致系统认为用户名不存在，从而重复创建账号。

为什么 count(1) 会返回 0？当 SQL 被错误追加了分页参数后，查询语句的实际执行形态可能变为：

select count(1) from sys_user where user_name = #{userName} limit 5

如果分页插件在底层将其包装为类似 limit 起始行, 偏移量 的形式，而当前线程遗留的分页参数是一个较大的偏移量时，聚合查询可能返回空结果，也可能返回异常值。对于以“存在性判断”为目的的查询，一次空结果便足以让业务逻辑做出完全相反的判断。

2. 下拉列表只能查出少量数据

另一个典型场景是分类下拉列表接口。该接口没有手动传入任何分页参数，但返回结果却始终只有 5 条。后来通过日志确认，实际执行 SQL 被追加了 limit 5。

这说明，分页参数并非来自当前接口自身，而是从同一个线程此前执行的某个分页查询中“继承”了下来。由于分页状态存储在线程局部变量中，而线程池会复用线程，所以一旦某次请求未清理分页状态，后续被调度到同一线程的请求就会被污染。

3. 修改密码时 update 语句直接报错

后台管理员重置用户密码时，系统抛出异常，错误信息大致为：SQL 语句异常，update 语句不认识 limit。

这说明分页参数已经影响到了写操作。对于 update、insert 或 delete 语句，通常不会拼接 limit，一旦被强制追加，数据库解析失败，直接抛出异常。此类错误相对容易定位，因为报错信息明确指出了问题出自分页片段。

三、根因分析：ThreadLocal 如何成为“污染源”

分页组件为了在同一个线程内保持分页状态，常采用 ThreadLocal 存储当前请求的分页参数。典型逻辑如下：

PageHelper.startPage(pageNum, pageSize);
List<User> users = userMapper.selectUserList();
PageInfo<User> pageInfo = new PageInfo<>(users);

使用完毕后，组件会在某些生命周期节点自动清理分页状态。但在以下情况下，清理逻辑可能失效：

1. 业务方法抛出异常，导致后续清理代码未被执行；
2. 业务代码提前返回，绕过了清理入口；
3. 异步任务或子线程中执行数据库操作，但组件未适配该执行模型；
4. 多个数据库操作共享同一线程时，分页参数被重复使用。

当线程池调度该线程处理下一条请求时，如果分页参数仍然存在，就会对后续 SQL 产生影响。值得注意的是，这种影响不是必然导致错误，而是取决于遗留分页参数与当前 SQL 的组合是否触发异常。因此，故障往往表现为“偶发”“高并发时才出现”“重新登录后又正常”。

例如，遗留的 pageNum = 3, pageSize = 5 对于一条 select 语句可能不会报错，但会静默改变返回结果；而对于 update 语句，拼接 limit 后则直接产生语法错误。

四、连锁反应的形成机制

分页污染之所以具有“连锁反应”特征，是因为同一个线程在执行完分页查询后，通常还会连续执行多个数据库操作。一个典型的请求链路可能如下：

1. 用户提交注册请求；
2. 系统执行用户名唯一性校验查询，此时被遗留分页参数影响，返回错误结果；
3. 系统执行用户信息插入操作，SQL 被追加分页片段，直接报错；
4. 异常被全局异常处理器捕获，前端仅显示“系统繁忙”；
5. 用户重新提交请求，但此时线程可能已经切换，分页状态可能已被其他请求覆盖或清理；
6. 最终表现为“时好时坏”。

由于不同接口对分页片段的兼容性不同，污染造成的后果也呈现多样性：

• 对 select 查询：可能静默返回错误数据量；
• 对 count 查询：可能返回错误统计结果；
• 对 insert / update / delete：可能直接触发数据库语法异常；
• 对批量操作：可能只处理部分数据；
• 对事务操作：可能因中间语句异常导致事务回滚。

五、排查路径：从 SQL 日志反推分页状态

当系统中出现上述“无法稳定复现”的问题时，建议从以下路径进行排查。

1. 开启 SQL 日志

在开发或预发环境中开启 SQL 输出，观察实际执行的语句是否被追加了 limit 片段。例如：

select * from sys_user where status = 1 limit 5

如果业务代码中并未设置分页，但日志中出现了 limit 5，即可确认存在分页泄漏。

2. 检查线程复用情况

确认应用容器是否使用线程池处理请求。线程池复用是分页污染能够跨请求传播的前提条件。如果每次请求都创建新线程，则不会出现此类问题。

3. 检查分页组件清理时机

观察分页组件在以下场景中的表现：

• 正常返回时是否清理；
• 抛出异常时是否清理；
• 提前返回时是否清理；
• 多层调用中是否重复设置分页；
• 是否与事务、拦截器、AOP 等机制产生交互。

4. 定位污染来源

通过输出线程 ID 与分页状态，可以找到污染发生前的最后一个分页查询。例如：

Thread-23 执行分页查询
Thread-23 执行 update 语句

如果两条语句在同一线程上连续执行，且前者设置了分页参数，后者没有清理，即可定位根因。

六、防御式编程建议

1. 尽量使用局部传参方式

对于简单查询，优先通过 DAO 或 Mapper 接口直接传入分页条件，使分页状态随方法参数传递，而不是依赖线程局部变量。这种方式可读性更强，生命周期也更容易控制。

2. 缩小分页作用范围

分页代码应紧邻需要分页的查询语句，避免在分页设置与真正查询之间插入过多业务逻辑，减少异常导致状态残留的概率。

3. 业务方法出口统一清理

在 finally 块中显式清理分页状态，保证无论正常返回还是异常抛出，分页状态都会被释放。例如：

try {
    PageHelper.startPage(pageNum, pageSize);
    return mapper.selectList();
} finally {
    PageHelper.clearPage();
}

这种写法可以显著降低状态泄漏的风险。

4. 避免在事务内部随意切换分页

在事务跨度较长的业务方法中，应尽量避免多次设置分页，或在设置前确认当前线程是否已有分页状态。必要时可采用“先查询数据，再组装分页信息”的两段式写法。

5. 对写操作增加保护

对于 insert、update、delete 等语句，在执行前可主动清理线程中的分页状态。虽然这种操作可能影响正常的批量逻辑，但对于多数后台系统而言，写操作不应受分页组件影响。

七、总结：分页便利性背后的线程级状态管理

分页插件通过 ThreadLocal 实现分页参数的透明传递，确实让开发者少写了很多重复代码。但便利性的前提是：线程局部状态的生命周期必须与业务请求严格对齐。一旦出现异常路径、提前返回或线程复用，分页状态就可能泄漏，进而对同线程上的后续 SQL 操作产生不可预知的影响。

这类问题的典型特点是：错误现象多样、复现概率低、与具体业务逻辑弱相关。它提醒我们，在使用任何基于线程局部变量的组件时，都需要关注其状态清理机制与异常场景下的表现。对于分页功能而言，显式清理、局部传参、缩小作用域，以及充分的 SQL 日志监控，是避免这类连锁反应的关键手段。

理解分页状态的传播方式，远比记住某个组件的方法名更重要。因为真正的风险不在于分页参数本身，而在于状态在错误的时间出现在了错误的 SQL 上。