分页参数残留引发的连锁故障：从线程上下文泄漏到业务逻辑失守

一、引子：三个看似无关的诡异现象

在基于分页插件构建的持久层访问中，曾出现过一组令人费解的现象：

• 已注册的用户名可以再次注册成功，校验逻辑形同虚设；
• 查询全部分类的下拉列表，明明数据库里有十余条记录，接口却只返回五条；
• 管理员重置用户密码时，更新语句直接报错，提示语法无法识别附加的 limit 子句。

这三个现象分布在注册、查询、更新三条完全不同的业务链路上，表面毫无关联，但它们的根因指向同一处：分页参数在线程上下文中被设置后未被清理，随线程复用地扩散到了后续所有 SQL 执行中。本文将沿着“现象—定位—机理—防护”的路径，把这条隐蔽的故障链完整拆开。

二、现象拆解：两类故障表现

上述问题可以归为两类，它们的危害程度和排查难度截然不同。

2.1 显式报错型：语法层面的直接失败

更新语句、插入语句本身不支持 limit 子句。当分页插件在线程变量中残留了 pageNum、pageSize 等参数，拦截器在执行 SQL 前会尝试做分页改写，把 limit 拼接到 update、insert 语句末尾，数据库解析器随即抛出语法异常。这类问题的优点是暴露充分——错误信息明确指向 SQL 语句异常，开发者顺着堆栈很快能定位到分页拦截器。

2.2 静默逻辑错误型：没有异常的业务失真

更危险的是第二类。以用户名唯一性校验为例，其 SQL 形如：

<select id="checkUserNameUnique" parameterType="String" resultType="int">
    select count(1) from sys_user where user_name = #{userName} limit 1
</select>

语句本身写了 limit 1，用于只判断存在性、减少扫描。但如果线程中残留了分页参数（例如 pageSize=5），拦截器会在此基础上再做一次分页包装，生成嵌套的 limit 结构或改变结果集范围。当校验逻辑返回的计数与预期不符时，业务代码中其实存在异常抛出，例如：

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

但当校验结果被分页参数污染后，判定分支可能走向错误方向；即便内部抛出了异常，也会被全局异常处理器捕获并吞掉，最终表现为“接口正常返回、但业务结果错误”。用户因此可以重复注册，而日志里只有一条被淹没的警告。

2.3 数据量失真型：返回条数被意外截断

下拉列表查询是最典型的受害者。开发者没有传任何分页参数，预期返回全量分类，实际却只拿到五条。原因在于：该请求复用了线程池中的某个线程，而该线程此前处理过一个带 pageSize=5 的分页请求，分页参数被写入线程上下文后未清除，于是这次“本不分页”的查询被强行加上了 limit 5。返回量错误，但没有任何报错，若前端未做总量校验，这类缺陷可以长期潜伏。

三、机理剖析：线程上下文为何会“记住”上一次请求

3.1 分页参数的存放位置

主流分页插件普遍采用“拦截器 + 线程变量”的设计：调用方在执行查询前通过静态方法设置分页参数，参数被存入当前线程的 ThreadLocal；拦截器在 SQL 执行前读取该变量，动态改写 SQL 并追加分页子句；查询结束后，理论上应清理该变量。

3.2 泄漏的两个前提

泄漏的发生需要同时满足两个条件：

1. 设置与清理不对称：某些代码路径只调用设置方法，却没有对应的清理动作，例如在 Service 中调用分页方法后提前 return、抛出异常，或跨方法传递时分页参数被“顺手”设置。
2. 线程复用：Web 容器普遍使用线程池，一个线程处理完请求后不会销毁，而是归还池中等待下一个任务。残留在 ThreadLocal 中的参数因此被下一个请求“继承”。

这也解释了一个关键细节：异常不是每次出现，而是有一定概率。是否触发取决于当前请求是否恰好落在那个“脏线程”上，以及该线程上一次执行的分页参数是什么。并发越高、线程池越小，复用的概率越大，故障触发率随之上升。这也正是此类问题最难复现、最容易被误判为“偶发 bug”的原因。

3.3 为什么嵌套 SQL 不会总是报错

值得补充的是，分页拦截器对已含 limit 的 SQL 处理策略因实现而异：有的会跳过改写，有的会做嵌套包装。前者导致参数残留“看似无害”却悄悄影响结果范围，后者则可能生成非法语法。这种实现差异进一步加剧了问题的隐蔽性——同一份代码在不同环境下表现不同。

四、系统性防护：从“事后排查”到“事前约束”

4.1 明确清理时机

最直接的做法是保证设置与清理成对出现。推荐将分页调用封装在统一模板中：

public <T> PageResult<T> doPage(int pageNum, int pageSize, Supplier<List<T>> query) {
    try {
        PageHelper.startPage(pageNum, pageSize);
        List<T> list = query.get();
        return buildPageResult(list);
    } finally {
        PageHelper.clearPage(); // 无论正常返回还是异常，均清理
    }
}

finally 块是關鍵：任何提前 return、运行时异常都不会绕过清理逻辑。

4.2 收紧分页入口

在架构层面，应禁止在非查询链路上调用分页设置方法。可通过以下手段约束：

• 代码规范与评审清单：将“分页设置必须与清理配对”写入团队规范，评审时重点检查；
• 静态扫描规则：对分页设置方法的调用点做扫描，标记缺少清理的代码路径；
• 拦截器兜底：在请求入口处注册统一拦截器，在请求结束时强制清理线程变量，作为最后一道防线。

public class PageContextCleanupInterceptor implements HandlerInterceptor {
    @Override
    public void afterCompletion(HttpServletRequest request,
                                HttpServletResponse response,
                                Object handler, Exception ex) {
        PageHelper.clearPage(); // 请求结束强制清理，防止污染线程池
    }
}

4.3 校验类 SQL 的防御性写法

对于唯一性校验这类“只关心存在性”的查询，建议避免依赖 limit 语义，改用更明确的写法，并确保其执行路径不经过分页拦截器的改写范围：

// 显式关闭分页，避免继承线程残留参数
PageHelper.clearPage();
int count = userMapper.checkUserNameUnique(userName);

同时在业务层对返回值做严格断言，而不是仅比较枚举常量，降低“静默错误”逃逸的概率。

4.4 可观测性补强

由于此类问题具有概率性，建议在日志中记录每次 SQL 改写前后的语句与分页参数快照。当出现“语句被追加 limit”的异常记录时，可快速关联到具体请求与线程，缩短定位周期。

五、小结

分页参数残留的本质，是线程局部状态的生命周期管理失守。它不产生编译错误，也不总是抛出异常，却能同时污染注册校验、列表查询与更新语句，制造出一组看似毫无关联的故障。治理思路应落在三个层面：编码层面保证设置与清理解耦于业务逻辑、架构层面用拦截器做兜底清理、工程层面用规范与扫描把问题挡在上线之前。理解“线程复用 + 状态残留”这一组合条件，也就掌握了排查此类偶发故障的钥匙。