PageHelper使用offset分页时为何实际偏移量与预期不符？

Question

PageHelper 使用 `offset` 分页时偏移量“失准”，本质源于其默认分页模式与 MyBatis 执行逻辑的耦合偏差。当调用 `PageHelper.offsetPage(offset, size)` 时，PageHelper 并非直接生成 `LIMIT offset, size` SQL，而是通过拦截 Executor，在 SQL 执行前动态重写为 `ROW_NUMBER() OVER()`（Oracle/SQL Server）或 `LIMIT ? OFFSET ?`（MySQL 5.7+），但**关键陷阱在于：offset 值会被 PageHelper 内部按当前线程 Page 参数自动归一化处理**。若此前已存在未清空的 Page 线程变量（如上一次查询未调用 `PageHelper.clearPage()`），或误在 `selectList()` 后再次调用 `offsetPage()`，PageHelper 会叠加计算 offset，导致实际跳过的记录数远超预期。此外，MyBatis 的 `RowBounds` 与 PageHelper 混用、或 XML 中手动写 `limit #{offset}, #{size}` 也会绕过 PageHelper 的上下文管理，造成 offset 语义错乱。根本解法是：严格遵循「一次查询、一次 PageHelper 调用、调用后及时 clear」原则，并避免与原生分页机制混用。

Answer 1

```html

一、现象层：Offset 分页“跳页”或“漏数据”的典型表现

开发者常遇到：调用 PageHelper.offsetPage(100, 20) 本意跳过前100条取第101–120条，结果返回第121–140条；或第一页正常，第二页起数据重复/错位。日志中 SQL 显示 LIMIT 120 OFFSET 100（而非预期的 LIMIT 20 OFFSET 100），表明 offset 被二次叠加。该现象在高并发线程复用场景下尤为高频。

二、机制层：PageHelper 的线程级上下文耦合模型

PageHelper 基于 ThreadLocal 维护分页上下文，其 offsetPage(offset, size) 并非原子操作——它先读取当前线程中已存在的 Page 实例（若存在），再执行：
page.setOffset(page.getOffset() + offset); page.setSize(size);
这意味着：若上一请求遗留了 Page(offset=50, size=10) 未 clear()，本次调用 offsetPage(100, 20) 将实际生效 offset = 50 + 100 = 150。

三、执行层：SQL 重写逻辑与数据库方言的隐式适配

PageHelper 拦截 Executor.query() 后，根据数据库类型动态改写 SQL：

数据库	重写后 SQL 片段	关键约束
MySQL 5.7+	LIMIT ? OFFSET ?	OFFSET 值 = Page.offset（经归一化后）
Oracle 12c+	SELECT * FROM (SELECT ..., ROW_NUMBER() OVER(ORDER BY ...) rn FROM ...) WHERE rn BETWEEN ? AND ?	BETWEEN 下界 = Page.offset + 1

四、冲突层：多分页机制混用引发的语义覆盖

以下三种混用模式必然导致 offset 失准：

1. 在同一线程中先调用 PageHelper.startPage(1,10)，再调用 offsetPage(50,20) —— PageHelper 叠加计算
2. Mapper 接口方法签名含 RowBounds 参数，同时使用 @Select 注解 —— MyBatis 原生 RowBounds 优先级高于 PageHelper 拦截器
3. XML 中硬编码 <bind name="limitClause" value="'LIMIT ' + offset + ', ' + size"/> —— 完全绕过 PageHelper 上下文管理

五、诊断层：精准定位 offset 归一化的运行时证据

可通过以下代码验证当前线程 Page 状态：

Page<?> page = PageHelper.getLocalPage();
if (page != null) {
    System.out.println("Current Page: offset=" + page.getOffset() 
                     + ", size=" + page.getSize() 
                     + ", reasonable=" + page.isReasonable());
}
// 输出示例：Current Page: offset=150, size=20, reasonable=true

六、治理层：工程级防御性编程规范

必须强制实施以下三原则（缺一不可）：

• 单次查询单次 PageHelper 调用：每个业务方法内仅允许一处 offsetPage() 或 startPage()
• 调用后立即 clear：在 selectList() 返回后、方法退出前执行 PageHelper.clearPage()
• 零混用契约：禁用 RowBounds 参数；禁止 XML 中出现任何 LIMIT/OFFSET/ROWNUM 相关硬编码

七、架构层：基于 AOP 的自动化清理增强方案

为规避人工疏漏，推荐使用 Spring AOP 实现自动清理：

@Aspect
@Component
public class PageHelperClearAspect {
    @After("execution(* com.example.mapper..*.*(..)) && @annotation(org.apache.ibatis.annotations.Select)")
    public void clearAfterMapperCall(JoinPoint jp) {
        PageHelper.clearPage(); // 确保每次 Mapper 调用后清空
    }
}

八、演进层：向无状态分页范式迁移的长期路径

面向微服务与云原生，建议逐步过渡至 Cursor-based Pagination（游标分页）：

graph LR
A[客户端传 last_id 或 created_at] --> B{服务端校验游标有效性}
B -->|有效| C[WHERE id > last_id ORDER BY id LIMIT 20]
B -->|无效| D[返回 400 Bad Request]
C --> E[返回数据 + next_cursor]

九、验证层：单元测试覆盖 offset 边界场景

关键测试用例应包含：

• 连续两次 offsetPage(0,10) 后调用 offsetPage(10,10) —— 验证是否叠加
• 跨线程传递 PageHelper 上下文（如 CompletableFuture）—— 验证 ThreadLocal 隔离性
• 在 try-finally 中遗漏 clearPage() —— 模拟线程池复用污染

十、认知层：理解 PageHelper 本质是“上下文增强器”，而非“SQL 生成器”

PageHelper 的核心价值在于对 MyBatis 执行链路的上下文注入与拦截，其 offset 语义始终依附于 ThreadLocal 中的 Page 实例生命周期。任何脱离该生命周期的操作（如手动拼接 SQL、混用 RowBounds、跨线程共享 Page 对象），都将导致分页语义断裂。真正的稳定性不来自框架魔法，而源于对线程上下文边界的敬畏与显式管控。

```