1. 项目概述最近在重构公司的一个老项目时发现系统中存在大量重复的分页代码逻辑。作为一个有追求的开发者我决定将这些重复代码抽象成一个通用的MyBatis分页插件。这不仅能让代码更加整洁也能为团队后续开发提供统一的分页解决方案。这个插件需要实现的核心功能是通过简单的参数配置自动拦截SQL语句并添加分页逻辑同时返回包含分页信息的标准数据结构。在Spring Boot项目中我们希望使用方式尽可能简单比如通过一个注解或者方法参数就能启用分页功能。2. 技术选型与设计思路2.1 为什么选择MyBatis插件机制MyBatis提供了强大的插件机制允许我们在SQL执行的生命周期中插入自定义逻辑。通过实现Interceptor接口我们可以拦截Executor的query方法这正是实现分页功能的理想切入点。相比在业务代码中手动处理分页插件方式有以下优势业务代码无需关心分页实现细节统一的分页逻辑避免各写各的导致风格不一致便于后期维护和功能升级2.2 核心设计要点在设计这个分页插件时我主要考虑了以下几个关键点拦截时机选择应该在SQL被执行前拦截添加LIMIT语句分页参数传递支持多种参数传递方式注解、方法参数等总数查询优化避免每次都执行COUNT查询多数据库兼容需要支持MySQL、Oracle等不同数据库方言性能考虑尽量减少插件带来的性能损耗3. 实现细节解析3.1 插件基础结构首先创建一个实现了Interceptor接口的类Intercepts({ Signature(type Executor.class, method query, args {MappedStatement.class, Object.class, RowBounds.class, ResultHandler.class}) }) public class PaginationInterceptor implements Interceptor { // 插件逻辑实现 }这个拦截器会拦截Executor的query方法这是MyBatis执行查询的核心方法。3.2 分页参数处理我们需要设计灵活的参数传递方式。以下是几种常见的方案方法参数传递public ListUser getUsers(int pageNum, int pageSize);注解方式Pageable public ListUser getUsers();统一分页参数public ListUser getUsers(PageRequest pageRequest);在实际实现中我选择了第三种方式因为它最灵活且类型安全。PageRequest类定义如下public class PageRequest { private int pageNum; private int pageSize; private boolean count true; // getters setters }3.3 SQL改写逻辑核心的SQL改写发生在拦截器的intercept方法中Override public Object intercept(Invocation invocation) throws Throwable { Object[] args invocation.getArgs(); MappedStatement ms (MappedStatement) args[0]; Object parameter args[1]; // 解析分页参数 PageRequest pageRequest parsePageRequest(parameter); if (pageRequest null) { return invocation.proceed(); } // 获取原始SQL BoundSql boundSql ms.getBoundSql(parameter); String originalSql boundSql.getSql(); // 生成分页SQL String pagedSql generatePagedSql(originalSql, pageRequest); // 修改MappedStatement MappedStatement newMs copyMappedStatement(ms, pagedSql); args[0] newMs; // 执行查询 List? result (List?) invocation.proceed(); // 处理总数查询 if (pageRequest.isCount()) { int total getTotalCount(ms, parameter, originalSql); return new PageImpl(result, pageRequest, total); } return new PageImpl(result, pageRequest); }3.4 多数据库支持不同数据库的分页语法差异很大我们需要为每种数据库实现特定的SQL生成逻辑public interface Dialect { String getPagedSql(String sql, PageRequest pageRequest); String getCountSql(String sql); } // MySQL实现 public class MySqlDialect implements Dialect { Override public String getPagedSql(String sql, PageRequest pageRequest) { return sql LIMIT pageRequest.getOffset() , pageRequest.getPageSize(); } Override public String getCountSql(String sql) { return SELECT COUNT(1) FROM ( sql ) tmp_count; } }4. 性能优化技巧4.1 缓存MappedStatement每次分页查询都需要创建新的MappedStatement这会带来一定的性能开销。我们可以通过缓存来优化private static final MapString, MappedStatement MS_CACHE new ConcurrentHashMap(); private MappedStatement copyMappedStatement(MappedStatement ms, String sql) { String key ms.getId() : sql.hashCode(); return MS_CACHE.computeIfAbsent(key, k - { // 创建新的MappedStatement // ... }); }4.2 避免不必要的COUNT查询在某些场景下我们可能不需要获取总记录数。通过PageRequest的count参数可以控制public ListUser getUsers() { PageRequest pageRequest new PageRequest(1, 10); pageRequest.setCount(false); // 不执行COUNT查询 // ... }4.3 使用ThreadLocal存储分页参数为了避免在每个方法中都传递PageRequest参数可以使用ThreadLocalpublic class PageContext { private static final ThreadLocalPageRequest PAGE_HOLDER new ThreadLocal(); public static void setPageRequest(PageRequest pageRequest) { PAGE_HOLDER.set(pageRequest); } public static PageRequest getPageRequest() { return PAGE_HOLDER.get(); } public static void clear() { PAGE_HOLDER.remove(); } }然后在拦截器中可以直接获取PageRequest pageRequest PageContext.getPageRequest();5. Spring Boot集成5.1 自动配置为了让插件在Spring Boot中开箱即用我们可以创建一个自动配置类Configuration ConditionalOnClass(SqlSessionFactory.class) public class MyBatisPaginationAutoConfiguration { Bean ConditionalOnMissingBean public PaginationInterceptor paginationInterceptor() { PaginationInterceptor interceptor new PaginationInterceptor(); interceptor.setDialect(new MySqlDialect()); return interceptor; } }5.2 与Spring Data风格统一为了让API风格更一致我们可以借鉴Spring Data的分页设计public interface PageT extends ListT { int getTotalPages(); long getTotalElements(); int getPageNumber(); int getPageSize(); // ... }这样我们的分页结果就能与Spring生态更好地融合。6. 测试与验证6.1 单元测试为分页插件编写全面的单元测试Test public void testPagination() { SqlSession sqlSession sqlSessionFactory.openSession(); try { UserMapper mapper sqlSession.getMapper(UserMapper.class); // 设置分页参数 PageContext.setPageRequest(new PageRequest(1, 10)); ListUser users mapper.selectAll(); assertTrue(users instanceof Page); PageUser page (PageUser) users; assertEquals(10, page.size()); assertEquals(1, page.getPageNumber()); assertTrue(page.getTotalElements() 0); } finally { PageContext.clear(); sqlSession.close(); } }6.2 性能测试使用JMH进行基准测试比较使用插件前后的性能差异Benchmark BenchmarkMode(Mode.AverageTime) OutputTimeUnit(TimeUnit.MILLISECONDS) public void testPaginationPerformance() { // 测试代码 }7. 常见问题与解决方案7.1 SQL注入风险在拼接分页参数时要特别注意SQL注入问题。我们的实现中分页参数是通过PreparedStatement设置的因此是安全的String pagedSql originalSql LIMIT ?, ?; // ... statement.setInt(1, pageRequest.getOffset()); statement.setInt(2, pageRequest.getPageSize());7.2 嵌套查询问题当SQL中包含子查询时简单的字符串拼接可能会导致语法错误。我们需要更智能的SQL解析public String getPagedSql(String sql, PageRequest pageRequest) { // 使用SQL解析器识别主查询 String mainSelect extractMainSelect(sql); return mainSelect LIMIT pageRequest.getOffset() , pageRequest.getPageSize(); }7.3 与MyBatis其他插件冲突如果项目中使用了其他MyBatis插件可能会发生拦截器执行顺序问题。可以通过Intercepts注解的order属性控制Intercepts(value {...}, order 100) public class PaginationInterceptor implements Interceptor { // ... }8. 高级功能扩展8.1 动态分页策略可以根据查询结果数量自动调整分页策略if (total 10000) { // 大数据量分页优化 return useCursorPaging(); } else { // 常规分页 return useLimitPaging(); }8.2 分页查询缓存对于不常变动的数据可以缓存分页结果Cacheable(value userPages, key #pageRequest.hashCode()) public PageUser getUsers(PageRequest pageRequest) { // ... }8.3 多数据源支持在多数据源环境下需要为每个SqlSessionFactory配置独立的插件实例Bean public PaginationInterceptor paginationInterceptor1() { PaginationInterceptor interceptor new PaginationInterceptor(); interceptor.setDialect(new MySqlDialect()); return interceptor; } Bean public PaginationInterceptor paginationInterceptor2() { PaginationInterceptor interceptor new PaginationInterceptor(); interceptor.setDialect(new OracleDialect()); return interceptor; }9. 实际应用建议在实际项目中使用这个分页插件时我有以下几点建议统一分页参数命名全项目统一使用pageNum和pageSize避免混乱合理设置默认页大小避免一次性查询过多数据监控分页查询性能特别关注大数据量下的分页性能考虑使用keyset分页对于深度分页场景考虑使用基于ID的分页方式10. 与其他方案的对比10.1 与PageHelper对比相比流行的PageHelper插件我们的实现有以下特点更轻量不依赖其他库更容易定制和扩展与Spring Data风格更一致更透明的实现便于调试10.2 与JPA分页对比JPA的分页功能很强大但我们的方案更适合MyBatis生态不强制使用JPA对现有MyBatis项目侵入性小可以充分利用MyBatis的灵活性11. 源码解析与调试技巧11.1 插件执行流程理解MyBatis插件的执行流程对调试很有帮助插件初始化时会被添加到拦截器链中当目标方法被调用时拦截器链按顺序执行每个拦截器可以决定是否继续执行链11.2 调试技巧调试MyBatis插件时可以重点关注BoundSQL对象查看最终执行的SQLMappedStatement包含SQL映射信息参数对象检查分页参数是否正确解析12. 总结与展望通过这个项目我深入理解了MyBatis插件机制和分页实现的各个细节。这个分页插件已经在我们的生产环境中稳定运行显著提高了开发效率。未来可以考虑的改进方向包括支持更多数据库方言实现基于游标的分页方案增加查询性能分析功能提供更丰富的监控指标
1. 项目概述最近在重构公司的一个老项目时发现系统中存在大量重复的分页代码逻辑。作为一个有追求的开发者我决定将这些重复代码抽象成一个通用的MyBatis分页插件。这不仅能让代码更加整洁也能为团队后续开发提供统一的分页解决方案。这个插件需要实现的核心功能是通过简单的参数配置自动拦截SQL语句并添加分页逻辑同时返回包含分页信息的标准数据结构。在Spring Boot项目中我们希望使用方式尽可能简单比如通过一个注解或者方法参数就能启用分页功能。2. 技术选型与设计思路2.1 为什么选择MyBatis插件机制MyBatis提供了强大的插件机制允许我们在SQL执行的生命周期中插入自定义逻辑。通过实现Interceptor接口我们可以拦截Executor的query方法这正是实现分页功能的理想切入点。相比在业务代码中手动处理分页插件方式有以下优势业务代码无需关心分页实现细节统一的分页逻辑避免各写各的导致风格不一致便于后期维护和功能升级2.2 核心设计要点在设计这个分页插件时我主要考虑了以下几个关键点拦截时机选择应该在SQL被执行前拦截添加LIMIT语句分页参数传递支持多种参数传递方式注解、方法参数等总数查询优化避免每次都执行COUNT查询多数据库兼容需要支持MySQL、Oracle等不同数据库方言性能考虑尽量减少插件带来的性能损耗3. 实现细节解析3.1 插件基础结构首先创建一个实现了Interceptor接口的类Intercepts({ Signature(type Executor.class, method query, args {MappedStatement.class, Object.class, RowBounds.class, ResultHandler.class}) }) public class PaginationInterceptor implements Interceptor { // 插件逻辑实现 }这个拦截器会拦截Executor的query方法这是MyBatis执行查询的核心方法。3.2 分页参数处理我们需要设计灵活的参数传递方式。以下是几种常见的方案方法参数传递public ListUser getUsers(int pageNum, int pageSize);注解方式Pageable public ListUser getUsers();统一分页参数public ListUser getUsers(PageRequest pageRequest);在实际实现中我选择了第三种方式因为它最灵活且类型安全。PageRequest类定义如下public class PageRequest { private int pageNum; private int pageSize; private boolean count true; // getters setters }3.3 SQL改写逻辑核心的SQL改写发生在拦截器的intercept方法中Override public Object intercept(Invocation invocation) throws Throwable { Object[] args invocation.getArgs(); MappedStatement ms (MappedStatement) args[0]; Object parameter args[1]; // 解析分页参数 PageRequest pageRequest parsePageRequest(parameter); if (pageRequest null) { return invocation.proceed(); } // 获取原始SQL BoundSql boundSql ms.getBoundSql(parameter); String originalSql boundSql.getSql(); // 生成分页SQL String pagedSql generatePagedSql(originalSql, pageRequest); // 修改MappedStatement MappedStatement newMs copyMappedStatement(ms, pagedSql); args[0] newMs; // 执行查询 List? result (List?) invocation.proceed(); // 处理总数查询 if (pageRequest.isCount()) { int total getTotalCount(ms, parameter, originalSql); return new PageImpl(result, pageRequest, total); } return new PageImpl(result, pageRequest); }3.4 多数据库支持不同数据库的分页语法差异很大我们需要为每种数据库实现特定的SQL生成逻辑public interface Dialect { String getPagedSql(String sql, PageRequest pageRequest); String getCountSql(String sql); } // MySQL实现 public class MySqlDialect implements Dialect { Override public String getPagedSql(String sql, PageRequest pageRequest) { return sql LIMIT pageRequest.getOffset() , pageRequest.getPageSize(); } Override public String getCountSql(String sql) { return SELECT COUNT(1) FROM ( sql ) tmp_count; } }4. 性能优化技巧4.1 缓存MappedStatement每次分页查询都需要创建新的MappedStatement这会带来一定的性能开销。我们可以通过缓存来优化private static final MapString, MappedStatement MS_CACHE new ConcurrentHashMap(); private MappedStatement copyMappedStatement(MappedStatement ms, String sql) { String key ms.getId() : sql.hashCode(); return MS_CACHE.computeIfAbsent(key, k - { // 创建新的MappedStatement // ... }); }4.2 避免不必要的COUNT查询在某些场景下我们可能不需要获取总记录数。通过PageRequest的count参数可以控制public ListUser getUsers() { PageRequest pageRequest new PageRequest(1, 10); pageRequest.setCount(false); // 不执行COUNT查询 // ... }4.3 使用ThreadLocal存储分页参数为了避免在每个方法中都传递PageRequest参数可以使用ThreadLocalpublic class PageContext { private static final ThreadLocalPageRequest PAGE_HOLDER new ThreadLocal(); public static void setPageRequest(PageRequest pageRequest) { PAGE_HOLDER.set(pageRequest); } public static PageRequest getPageRequest() { return PAGE_HOLDER.get(); } public static void clear() { PAGE_HOLDER.remove(); } }然后在拦截器中可以直接获取PageRequest pageRequest PageContext.getPageRequest();5. Spring Boot集成5.1 自动配置为了让插件在Spring Boot中开箱即用我们可以创建一个自动配置类Configuration ConditionalOnClass(SqlSessionFactory.class) public class MyBatisPaginationAutoConfiguration { Bean ConditionalOnMissingBean public PaginationInterceptor paginationInterceptor() { PaginationInterceptor interceptor new PaginationInterceptor(); interceptor.setDialect(new MySqlDialect()); return interceptor; } }5.2 与Spring Data风格统一为了让API风格更一致我们可以借鉴Spring Data的分页设计public interface PageT extends ListT { int getTotalPages(); long getTotalElements(); int getPageNumber(); int getPageSize(); // ... }这样我们的分页结果就能与Spring生态更好地融合。6. 测试与验证6.1 单元测试为分页插件编写全面的单元测试Test public void testPagination() { SqlSession sqlSession sqlSessionFactory.openSession(); try { UserMapper mapper sqlSession.getMapper(UserMapper.class); // 设置分页参数 PageContext.setPageRequest(new PageRequest(1, 10)); ListUser users mapper.selectAll(); assertTrue(users instanceof Page); PageUser page (PageUser) users; assertEquals(10, page.size()); assertEquals(1, page.getPageNumber()); assertTrue(page.getTotalElements() 0); } finally { PageContext.clear(); sqlSession.close(); } }6.2 性能测试使用JMH进行基准测试比较使用插件前后的性能差异Benchmark BenchmarkMode(Mode.AverageTime) OutputTimeUnit(TimeUnit.MILLISECONDS) public void testPaginationPerformance() { // 测试代码 }7. 常见问题与解决方案7.1 SQL注入风险在拼接分页参数时要特别注意SQL注入问题。我们的实现中分页参数是通过PreparedStatement设置的因此是安全的String pagedSql originalSql LIMIT ?, ?; // ... statement.setInt(1, pageRequest.getOffset()); statement.setInt(2, pageRequest.getPageSize());7.2 嵌套查询问题当SQL中包含子查询时简单的字符串拼接可能会导致语法错误。我们需要更智能的SQL解析public String getPagedSql(String sql, PageRequest pageRequest) { // 使用SQL解析器识别主查询 String mainSelect extractMainSelect(sql); return mainSelect LIMIT pageRequest.getOffset() , pageRequest.getPageSize(); }7.3 与MyBatis其他插件冲突如果项目中使用了其他MyBatis插件可能会发生拦截器执行顺序问题。可以通过Intercepts注解的order属性控制Intercepts(value {...}, order 100) public class PaginationInterceptor implements Interceptor { // ... }8. 高级功能扩展8.1 动态分页策略可以根据查询结果数量自动调整分页策略if (total 10000) { // 大数据量分页优化 return useCursorPaging(); } else { // 常规分页 return useLimitPaging(); }8.2 分页查询缓存对于不常变动的数据可以缓存分页结果Cacheable(value userPages, key #pageRequest.hashCode()) public PageUser getUsers(PageRequest pageRequest) { // ... }8.3 多数据源支持在多数据源环境下需要为每个SqlSessionFactory配置独立的插件实例Bean public PaginationInterceptor paginationInterceptor1() { PaginationInterceptor interceptor new PaginationInterceptor(); interceptor.setDialect(new MySqlDialect()); return interceptor; } Bean public PaginationInterceptor paginationInterceptor2() { PaginationInterceptor interceptor new PaginationInterceptor(); interceptor.setDialect(new OracleDialect()); return interceptor; }9. 实际应用建议在实际项目中使用这个分页插件时我有以下几点建议统一分页参数命名全项目统一使用pageNum和pageSize避免混乱合理设置默认页大小避免一次性查询过多数据监控分页查询性能特别关注大数据量下的分页性能考虑使用keyset分页对于深度分页场景考虑使用基于ID的分页方式10. 与其他方案的对比10.1 与PageHelper对比相比流行的PageHelper插件我们的实现有以下特点更轻量不依赖其他库更容易定制和扩展与Spring Data风格更一致更透明的实现便于调试10.2 与JPA分页对比JPA的分页功能很强大但我们的方案更适合MyBatis生态不强制使用JPA对现有MyBatis项目侵入性小可以充分利用MyBatis的灵活性11. 源码解析与调试技巧11.1 插件执行流程理解MyBatis插件的执行流程对调试很有帮助插件初始化时会被添加到拦截器链中当目标方法被调用时拦截器链按顺序执行每个拦截器可以决定是否继续执行链11.2 调试技巧调试MyBatis插件时可以重点关注BoundSQL对象查看最终执行的SQLMappedStatement包含SQL映射信息参数对象检查分页参数是否正确解析12. 总结与展望通过这个项目我深入理解了MyBatis插件机制和分页实现的各个细节。这个分页插件已经在我们的生产环境中稳定运行显著提高了开发效率。未来可以考虑的改进方向包括支持更多数据库方言实现基于游标的分页方案增加查询性能分析功能提供更丰富的监控指标
)
)
