SpringBoot3整合MyBatisPlus分页失效问题

Question

在Spring Boot 3整合MyBatis-Plus 3.5+版本时，常见分页功能失效问题：调用`PageHelper`或`IPage`进行分页查询时，返回结果未分页或总数错误。根本原因在于MyBatis-Plus的分页插件未正确注册为Bean，或配置类未使用`@Configuration`注解导致拦截器未生效。此外，Spring Boot 3基于Java 17+和模块化设计，若未适配新的代理机制或存在依赖冲突（如mybatis-spring-boot-starter版本不兼容），也会导致`PaginationInnerInterceptor`无法拦截SQL执行。需确保正确配置分页插件并检查依赖兼容性。

Answer 1

一、问题现象与初步排查

在使用 Spring Boot 3 整合 MyBatis-Plus 3.5+ 版本时，开发者常遇到分页功能失效的问题。典型表现为：调用 IPage 或第三方插件如 PageHelper 进行分页查询后，返回结果未按预期分页，或总记录数（total）始终为0/错误值。

• 现象1：SQL 执行无 LIMIT 子句，全量数据被加载
• 现象2：page.getTotal() 返回0或与实际不符
• 现象3：控制台日志中未见分页插件拦截日志
• 现象4：服务启动无异常，但分页逻辑“静默失效”

此类问题往往并非代码书写错误，而是配置链路中断所致。需从插件注册机制入手深入分析。

二、核心原理剖析：MyBatis 拦截器工作机制

MyBatis 的分页能力依赖于拦截器（Interceptor）对 Executor、StatementHandler 等核心组件的代理增强。MyBatis-Plus 使用 PaginationInnerInterceptor 实现自动分页改写 SQL。

组件	作用	是否必需
PaginationInnerInterceptor	重写SQL添加LIMIT/OFFSET	是
MyBatisSqlSessionFactoryBean	集成拦截器到会话工厂	是
@Configuration	确保类被Spring扫描并注册Bean	是
Mapper 接口返回 IPage<T>	触发分页逻辑入口	是

三、常见错误配置场景与诊断路径

1. 未将 PaginationInnerInterceptor 注册为 Spring Bean
2. 配置类缺少 @Configuration 注解，导致 Bean 未被加载
3. 使用了旧版 mybatis-spring-boot-starter 与 Spring Boot 3 不兼容
4. Java 17+ 的强封装性导致反射代理失败（特别是使用 JDK 动态代理时）
5. 多个分页插件冲突（如 PageHelper 与 MP 内置分页共存）
6. 事务管理器与拦截器顺序错乱
7. 自定义 SqlSessionFactory 配置覆盖了 MP 自动装配
8. 模块化项目中包扫描路径遗漏配置类
9. Spring AOP 代理模式未启用 CGLIB（影响某些拦截场景）
10. 日志级别过低，未能暴露插件初始化过程

四、正确配置示例与代码实现

@Configuration
@MapperScan("com.example.mapper")
public class MyBatisPlusConfig {

    /**
     * 注册分页插件 Bean
     */
    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        // 添加分页拦截器
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
        return interceptor;
    }
}
    

关键点说明：

• @Configuration 必须存在，否则 Spring 不会处理该类中的 @Bean
• MybatisPlusInterceptor 是 MP 3.5+ 的统一插件容器
• 推荐指定 DbType 以避免数据库方言识别错误

五、依赖版本兼容性矩阵

Spring Boot	MyBatis-Plus	mybatis-spring-boot-starter	Java Version	Status
3.1.x	3.5.3+	3.0.3	17+	✅ 兼容
3.2.x	3.5.5	3.0.3	17+	✅ 兼容
3.0.x	3.5.2	3.0.2	17	⚠️ 边界兼容
2.7.x	3.5.3	2.3.1	8~11	❌ 不适用
3.1.x	3.4.3	3.0.3	17+	❌ 插件缺失

六、调试流程图与排查路径

graph TD
            A[分页结果异常] --> B{是否返回IPage}
            B -- 否 --> C[修改Mapper方法签名]
            B -- 是 --> D[@Configuration类注册拦截器?]
            D -- 否 --> E[添加@Bean + @Configuration]
            D -- 是 --> F[检查starter版本兼容性]
            F --> G[查看启动日志是否有MP插件加载信息]
            G --> H{是否存在PaginationInnerInterceptor初始化日志?}
            H -- 否 --> I[检查@ComponentScan是否覆盖配置包]
            H -- 是 --> J[使用DEBUG日志观察SQL重写过程]
            J --> K[确认生成SQL含LIMIT/OFFSET]

七、高级注意事项与最佳实践

在微服务或模块化架构中，还需关注以下几点：

• 若使用 open-feign 或远程调用封装分页对象，需确保 IPage 可序列化
• 避免在同一个项目中混合使用 PageHelper 和 MP 分页，防止执行链混乱
• 建议开启 MyBatis 日志：logging.level.com.example.mapper=DEBUG
• 对于 Kotlin 用户，注意 suspend 函数与分页插件的协程兼容性
• 在 GraalVM 原生镜像构建中，需额外注册反射类
• 考虑结合 Spring Data Web 对 Pageable 参数支持，提升REST接口一致性
• 使用 @DS 多数据源时，确保每个数据源都应用分页插件
• 定期审查依赖树：mvn dependency:tree | grep mybatis