一、分页插件核心机制​

​1. 协同设计：Page 参数 + ThreadLocal​

​组件​	​作用​	​优势​	​局限​
​**Page 参数**​	业务层显式传递分页参数（页码、条数）	类型安全，接口自描述	无法被拦截器直接获取
​ThreadLocal​	框架层隐式跨组件传递分页参数	解耦拦截器与业务逻辑，支持复杂场景	需手动清理，过度使用易导致内存泄漏

​2. 工作流程

 

​二、关键问题深度解析​

​1. 为什么拦截器不能直接获取 Page 参数？​​

• ​根本原因​：MyBatis 拦截器 API 的 Invocation 对象仅提供原始参数数组，无法关联参数名。
• ​技术限制​：Java 编译后默认丢失方法参数名（需 -parameters 编译选项）。
• ​解决方案​：通过 ParameterUtils.findPage() 动态解析参数，辅以 ThreadLocal 跨组件传递。

​2. ThreadLocal 的必要性​

• ​解决痛点​：拦截器 → Executor → StatementHandler 调用链中分页参数需跨层级共享。
• ​线程安全​：每个请求独立存储，避免多线程竞争。
• ​典型场景​：

  // 分页插件内部
  String sql = dialect.buildPaginationSql(originalSql, PaginationContext.getPage());

​3. 类型安全与维护性问题​

​方案​	​类型安全​	​可维护性​	​典型问题​
仅用 ThreadLocal	❌	低（隐式依赖，需文档约定）	运行时 ClassCastException 风险
仅用 Page 参数	✅	高（接口明确）	拦截器无法识别参数
​两者结合​	✅	高（显隐互补）	需理解双重机制

---

​三、开发者常问问题​

​1. 分页失效的常见原因​

• ​未注册插件​：忘记配置 PaginationInnerInterceptor。
• ​同类调用​：直接调用内部方法（如 this.method()），绕过代理。
• ​私有方法​：@Transactional 注解在私有方法上无效。

​2. 如何优化深度分页？​​

• ​游标分页​：

  SELECT * FROM user WHERE id > 1000 ORDER BY id LIMIT 10

• ​缓存总数​：对稳定数据源缓存 total，避免重复 COUNT。

​3. 多租户与分页的优先级​

mybatis-plus:
  interceptors:
    - tenant:  # 先执行多租户
    - pagination  # 后执行分页

---

​四、最佳实践总结​

1. ​编码规范​

   • 始终通过 Page 参数显式传递分页需求。
   • 避免在异步任务中直接使用 ThreadLocal（需手动传递参数）。

2. ​性能优化​

   // 禁用不必要COUNT查询
   Page<User> page = new Page<>(1, 10).setSearchCount(false);

3. ​调试技巧​

   logging:
     level:
       com.baomidou.mybatisplus.extension.plugins.inner.PaginationInnerInterceptor: DEBUG

---

​五、设计思想提炼​

• ​显隐结合​：Page 参数满足业务表达力，ThreadLocal 解决框架技术限制。
• ​分层治理​：业务层关注语义，框架层处理实现细节。
• ​妥协的艺术​：在类型安全和实现复杂度间取得平衡。

通过理解这些设计权衡，开发者能更高效地使用和定制分页功能。