---

Spring Boot集成PageHelper：輕松實現數據庫分頁功能

---

1. 為什么需要分頁？

分頁是處理大數據量查詢的核心技術，其重要性體現在：

• 性能優化：避免單次查詢返回過多數據導致內存溢出或響應延遲。
• 用戶體驗：前端展示分頁導航，用戶可快速定位目標數據。
• 網絡開銷：減少不必要的數據傳輸，節省帶寬。

傳統分頁的痛點：

• 復雜SQL：需手動編寫LIMIT、OFFSET等分頁語句，尤其多表聯查時易出錯。
• 維護困難：分頁邏輯散落在多個DAO層方法中，修改分頁規則需全局調整。

---

2. PageHelper簡介

PageHelper是MyBatis的物理分頁插件，核心功能包括：

• 自動分頁：攔截SQL并動態添加分頁語句，無需修改原查詢邏輯。
• 多數據庫支持：自動識別MySQL、Oracle等方言，生成對應分頁語法。
• 無縫集成：與Spring Boot和MyBatis深度整合，僅需簡單配置即可使用。

優勢對比：

方案	代碼量	可維護性	跨數據庫支持
手寫SQL分頁	多	差	無
PageHelper	少	優	有
Spring Data JPA	中等	良	有

---

3. 環境準備

步驟1：創建Spring Boot項目
使用 Spring Initializr 生成項目，勾選：

• MyBatis Framework
• MySQL Driver（或其他數據庫驅動）

步驟2：添加PageHelper依賴

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

步驟3：配置數據源與分頁參數

# application.yml
spring:datasource:url: jdbc:mysql://localhost:3306/demo?useSSL=falseusername: rootpassword: 123456driver-class-name: com.mysql.cj.jdbc.Drivermybatis:mapper-locations: classpath:mapper/*.xmlpagehelper:helperDialect: mysql    # 指定數據庫方言reasonable: true        # 頁碼越界自動修正（如pageNum=100時返回最后一頁）supportMethodsArguments: true  # 支持通過方法參數傳遞分頁條件

---

4. 核心實現

4.1 創建實體類和Mapper接口

// User.java
@Data
public class User {private Long id;private String name;private String email;
}// UserMapper.java
@Mapper
public interface UserMapper {List<User> selectAllUsers();
}

4.2 編寫Mapper XML文件

<!-- resources/mapper/UserMapper.xml -->
<mapper namespace="com.example.mapper.UserMapper"><select id="selectAllUsers" resultType="User">SELECT id, name, email FROM user</select>
</mapper>

4.3 Service層實現分頁查詢

@Service
public class UserService {@Autowiredprivate UserMapper userMapper;public PageInfo<User> getUsers(int pageNum, int pageSize) {// 關鍵：調用startPage后第一個查詢自動分頁PageHelper.startPage(pageNum, pageSize);List<User> users = userMapper.selectAllUsers();return new PageInfo<>(users);}
}

4.4 Controller層暴露API

@RestController
@RequestMapping("/api/users")
public class UserController {@Autowiredprivate UserService userService;@GetMappingpublic ResponseEntity<PageInfo<User>> listUsers(@RequestParam(defaultValue = "1") int page,@RequestParam(defaultValue = "10") int size) {PageInfo<User> pageInfo = userService.getUsers(page, size);return ResponseEntity.ok(pageInfo);}
}

4.5 分頁結果示例
請求 GET /api/users?page=2&size=5 返回：

{"total": 50,"pageNum": 2,"pageSize": 5,"pages": 10,"list": [{"id": 6, "name": "User6", "email": "user6@example.com"},...]
}

---

5. 高級配置

5.1 自定義分頁參數

pagehelper:params: count=countSql  # 將COUNT查詢轉換為COUNT_SQL優化語句page-size-zero: true    # 允許pageSize=0時返回全部結果max-page-size: 100      # 限制每頁最大數據量

5.2 多數據源分頁

@Configuration
public class DataSourceConfig {@Bean@ConfigurationProperties("spring.datasource.db1")public DataSource db1DataSource() {return DataSourceBuilder.create().build();}@Beanpublic SqlSessionFactory db1SqlSessionFactory() throws Exception {SqlSessionFactoryBean factory = new SqlSessionFactoryBean();factory.setDataSource(db1DataSource());// 配置PageHelper插件PageInterceptor pageInterceptor = new PageInterceptor();Properties props = new Properties();props.setProperty("helperDialect", "mysql");pageInterceptor.setProperties(props);factory.setPlugins(pageInterceptor);return factory.getObject();}
}

5.3 與Spring Data JPA結合

• 適用場景：同時需要JPA的便捷CRUD和復雜SQL分頁。
• 實現方式：在JPA Repository中注入MyBatis Mapper，混合使用。

---

6. 常見問題與解決方案

問題1：分頁失效

• 排查步驟：
  1. 確認PageHelper.startPage()在查詢前調用。
  2. 檢查是否配置了多個MyBatis插件導致攔截順序沖突。

問題2：SQL注入風險

• 防御措施：
  • 避免直接拼接SQL參數，如ORDER BY ${sortField}。
  • 使用PageHelper的orderBy方法安全排序：

    PageHelper.startPage(1, 10).setOrderBy("id desc");
    

問題3：分頁結果不準確

• 原因：
  • 查詢包含GROUP BY或子查詢時，自動生成的COUNT語句可能錯誤。
• 解決：手動指定COUNT查詢：

  <select id="selectAllUsers" resultType="User">SELECT id, name FROM user
  </select>
  <select id="selectAllUsers_COUNT" resultType="Long">SELECT COUNT(1) FROM user
  </select>
  

---

7. 總結與擴展

適用場景：

• 后臺管理系統數據表格展示
• 移動端APP的分頁加載
• 大數據量報表分批處理

擴展學習：

• PageHelper官方文檔
• MyBatis動態SQL技巧
• 實戰案例：電商訂單分頁查詢

---

流程圖：PageHelper分頁流程

---

避坑指南：

1. 索引優化：確保分頁字段（如id）有索引，避免OFFSET過大時性能下降。
2. 參數校驗：校驗pageNum和pageSize的合法性，防止負數或超大值。
3. 線程安全：PageHelper.startPage()基于ThreadLocal，需注意異步場景下的數據隔離。

---

通過本文，您已掌握Spring Boot集成PageHelper的核心技巧。立即實踐，讓分頁功能從此高效又優雅！ 🚀