目錄：

1. 引言
2. 分頁查詢基礎回顧
   2.1 Spring Data JPA分頁接口
   2.2 Pageable與Page的使用
   2.3 常見分頁參數設計
3. Spring Data REST簡介
   3.1 HATEOAS與超媒體驅動API
   3.2 Spring Data REST核心功能
   3.3 自動暴露Repository接口
4. 整合Spring Boot與Spring Data REST
   4.1 項目依賴與配置
   4.2 自定義Repository REST資源
   4.3 分頁查詢自動鏈接示例
5. 高級定制：動態篩選與分頁導航
   5.1 Querydsl結合Spring Data REST
   5.2 參數解析與Specification實現
   5.3 自定義分頁元數據擴展
6. 實戰案例：商品管理微服務
   6.1 領域模型與數據庫設計
   6.2 常見分頁場景實現
   6.3 前端集成示例（Vue.js/Angular）
7. 性能優化策略
   7.1 避免N+1查詢與批量抓取
   7.2 索引與分區策略
   7.3 緩存分頁結果與Redis
8. 安全與限流
   8.1 JWT身份認證與權限控制
   8.2 分頁接口防刷策略
9. 常見問題與排查
   9.1 總頁數計算不準確
   9.2 路由403/404問題
   9.3 性能瓶頸定位

---

1. 引言

在現代微服務架構中，客戶端經常需要分頁加載海量數據，如電商商品、日志記錄或社交動態。傳統API往往返回固定格式的分頁結果，開發者需手動拼裝分頁鏈接，既繁瑣又易出錯。Spring Data REST基于HATEOAS超媒體原則，可自動生成上一頁、下一頁、首尾頁鏈接，實現零侵入式的數據導航效果。本文將帶領讀者一步步掌握Spring Boot分頁查詢進階技巧，助力打造高效、友好的RESTful分頁接口。

2. 分頁查詢基礎回顧

2.1 Spring Data JPA分頁接口
Spring Data JPA提供了PagingAndSortingRepository，繼承自CrudRepository，額外暴露了分頁和排序接口。常用方法：

public interface UserRepository extends PagingAndSortingRepository<User, Long> {// 繼承分頁與排序能力，無需額外定義
}

開發者可直接通過repository.findAll(Pageable pageable)獲取Page<T>對象，其中包含總記錄數、總頁數及當前頁內容。

2.2 Pageable與Page的使用
org.springframework.data.domain.Pageable用于封裝分頁請求參數，常見構造方式：

Pageable pageable = PageRequest.of(pageIndex, pageSize, Sort.by("createdAt").descending());
Page<User> page = userRepository.findAll(pageable);

Page<T>則包含：

• getContent()：當前頁列表
• getTotalPages()：總頁數
• hasNext() / hasPrevious()：是否可翻頁
• getPageable()：當前分頁參數

2.3 常見分頁參數設計
為了方便前端交互，我們一般在URL中使用?page=0&size=20&sort=createdAt,desc參數格式，Spring Boot通過PageableHandlerMethodArgumentResolver自動解析。可在配置中全局定制默認頁大小與最大頁大小：

spring:data:web:pageable:default-page-size: 20max-page-size: 100

3. Spring Data REST簡介

3.1 HATEOAS與超媒體驅動API
HATEOAS（Hypermedia as the Engine of Application State）是一種REST設計原則，強調服務端在響應中提供必要的鏈接，指導客戶端下一步操作。Spring HATEOAS提供EntityModel<T>和Link構建超媒體資源。

3.2 Spring Data REST核心功能
Spring Data REST通過掃描項目中繼承Repository的接口，自動生成對應的CRUD REST API，并支持分頁、排序、投影、事件攔截器等多項功能，極大降低開發成本。

3.3 自動暴露Repository接口
只需添加依賴：

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-data-rest</artifactId>
</dependency>

Spring Boot啟動后，訪問/users即可得到分頁響應：

{"_embedded": {"users": [...]},"page": {"size":20,"totalElements":100,"totalPages":5,"number":0},"_links": {"self":...,"next":...,"prev":...,"first":...,"last":...}
}

4. 整合Spring Boot與Spring Data REST

4.1 項目依賴與配置
在pom.xml中同時引入：

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-data-rest</artifactId>
</dependency>

在application.yml中開啟HATEOAS鏈接暴露：

spring:data:rest:default-page-size: 20max-page-size: 100base-path: /api

4.2 自定義Repository REST資源
若想自定義暴露路徑或方法名稱，可在接口上添加@RepositoryRestResource注解：

@RepositoryRestResource(path = "accounts", collectionResourceRel = "accounts")
public interface AccountRepository extends PagingAndSortingRepository<Account, Long> {Page<Account> findByStatus(@Param("status") String status, Pageable pageable);
}

訪問/api/accounts/search/findByStatus?status=ACTIVE即可分頁查詢。

4.3 分頁查詢自動鏈接示例
示例響應：

{"_embedded": {"accounts":[...]},"page":{"size":20,"totalElements":45,"totalPages":3,"number":1},"_links":{"self":{"href":"http://.../accounts?page=1&size=20"},"first":{"href":"...page=0"},"prev":{"href":"...page=0"},"next":{"href":"...page=2"},"last":{"href":"...page=2"}}
}

5. 高級定制：動態篩選與分頁導航

5.1 Querydsl結合Spring Data REST
集成Querydsl后，可動態構建復雜查詢：

public interface ProductRepository extends QuerydslPredicateExecutor<Product>, PagingAndSortingRepository<Product, Long> {}

前端傳入?predicate=name.contains=book;price.gt=100&page=0&size=10即可組合查詢和分頁。

5.2 參數解析與Specification實現
使用JpaSpecificationExecutor：

public interface OrderRepository extends JpaSpecificationExecutor<Order>, PagingAndSortingRepository<Order, Long> {}
// 構造Specification
Specification<Order> spec = (root, query, cb) -> cb.equal(root.get("status"), status);
Page<Order> result = orderRepository.findAll(spec, pageable);

通過自定義PageableHandlerMethodArgumentResolverCustomizer可讓REST端點解析spec參數。

5.3 自定義分頁元數據擴展
可實現RepresentationModelProcessor<CollectionModel<?>>，為分頁響應添加自定義元數據：

@Component
public class PageMetadataProcessor implements RepresentationModelProcessor<CollectionModel<?>> {@Overridepublic CollectionModel<?> process(CollectionModel<?> model) {model.add(Link.of("/api/docs/pagination", "pagination-docs"));return model;}
}

6. 實戰案例：商品管理微服務

6.1 領域模型與數據庫設計

• Product實體：id, name, description, price, category, createdAt
• 索引：price、category字段建立索引

6.2 常見分頁場景實現

• 全量分頁
• 分類篩選分頁：/products/search/findByCategory?category=electronics
• 價格區間分頁組合查詢

6.3 前端集成示例（Vue.js）

async fetchProducts(page = 0) {const res = await axios.get(`/api/products?page=${page}&size=20`);this.products = res.data._embedded.products;this.links = res.data._links;
}

通過links.next.href動態生成下一頁按鈕。

7. 性能優化策略

7.1 避免N+1查詢與批量抓取
使用@EntityGraph或join fetch解決懶加載觸發的N+1問題。

7.2 索引與分區策略
針對大表，可考慮范圍分區或HASH分區，并對分頁字段進行復合索引。

7.3 緩存分頁結果與Redis
基于Spring Cache將分頁結果按頁存入Redis，減少數據庫壓力。

8. 安全與限流

8.1 JWT身份認證與權限控制
通過@PreAuthorize("hasRole('ROLE_USER')")控制不同分頁接口訪問權限。

8.2 分頁接口防刷策略
基于令牌桶算法對分頁請求進行限流，并結合用戶身份鑒別。

9. 常見問題與排查

9.1 總頁數計算不準確
檢查totalElements返回值是否受到過濾器或Specification影響。

9.2 路由403/404問題
確認Repository路徑與base-path配置一致，并檢查CORS策略。

9.3 性能瓶頸定位
使用Spring Boot Actuator和Micrometer進行請求跟蹤與時序數據庫監控。