PageHelper.startPage()的坑

### PageHelper.startPage 方法常见问题及解决方法

#### 设置分页参数后未立即执行查询语句
如果 `PageHelper.startPage` 调用之后并没有紧跟着 MyBatis 的查询操作，而是进行了其他业务逻辑处理，则可能导致分页功能失效或结果异常。这是因为 `PageHelper.startPage` 只影响紧接着的第一个查询语句[^2]。

// 错误示范：不连续的操作可能会导致分页失败
PageHelper.startPage(1, 10);
doSomeBusinessLogic(); // 中间有额外的业务逻辑
List<User> users = userMapper.selectUsers();

为了确保分页正常工作，在调用了 `PageHelper.startPage()` 后应立刻执行对应的查询语句：

// 正确做法：保持 startPage 和 select 操作紧密相连
PageHelper.startPage(1, 10);
List<User> users = userMapper.selectUsers();

#### 导入错误的包名
有时开发者会不小心导入了错误版本的类库，比如应该使用的是 `com.github.pagehelper.PageHelper` 却误用了其他的同名类。这通常发生在项目依赖管理不当的情况下[^4]。

确保正确引入如下所示的依赖项并配置好 Maven 或 Gradle 文件中的相应坐标：

<!-- Maven -->
<dependency>
    <groupId>com.github.pagehelper</groupId>
    <artifactId>pagehelper-spring-boot-starter</artifactId>
    <version>x.x.x</version>
</dependency>

对于 Java 类文件来说，应当这样声明所需的静态导入：

import com.github.pagehelper.Page;
import com.github.pagehelper.PageHelper;

#### 数据源切换引起的分页混乱
当应用程序存在多个数据库连接池时（例如主从分离架构），若在事务内频繁更换数据源而没有重置分页插件的状态，那么就有可能造成页面大小和当前页码设置丢失等问题。因此建议在一个完整的事务单元内部只针对单一的数据源进行操作，并且每次改变数据源之前都要重新初始化分页环境变量[^3]。

#### 多线程环境下共享同一个 SessionFactory 实例引发的竞争条件
由于 Hibernate/MyBatis 默认情况下会在多线程场景下共用相同的 SqlSession 对象实例来访问持久层资源，所以在并发请求较多的时候容易发生竞争状态从而破坏原有的分页机制。为了避免这种情况的发生，可以在应用启动阶段通过自定义拦截器等方式为每一个独立的工作线程分配单独使用的 Session 工厂对象。