1. 項目緣起為什么JPA分頁查詢值得單獨拎出來講最近在帶幾個新同事做項目發(fā)現(xiàn)一個挺有意思的現(xiàn)象大家用SpringBoot JPA做簡單的findAll()分頁都挺溜Pageable一傳Page對象一收前端表格數(shù)據(jù)就出來了。但一旦需求稍微復(fù)雜點比如要加幾個動態(tài)查詢條件或者需要寫個稍微復(fù)雜點的JOIN查詢代碼就開始變得五花八門有的用Query寫原生SQL有的在Service層瘋狂拼接if-else還有的甚至繞回去用MyBatis-Plus了。問他們?yōu)槭裁椿卮鹜恰癑PA的動態(tài)查詢不太熟”、“怕Specification寫錯了性能不好”、“Query的分頁總感覺有點別扭”。這讓我想起自己剛用JPA那會兒也是這么過來的。JPA的分頁表面上就那幾招但真想用得順手、寫得優(yōu)雅、跑得高效里頭的門道其實不少。它不像MyBatis-Plus那樣給你一個包裝好的Page對象和清晰的Wrapper鏈式調(diào)用JPA的風(fēng)格更“Spring”一些講究的是聲明式和規(guī)范Specification。用好了代碼簡潔得像詩用不好就是一坨隱藏在Repository接口里的“屎山”。所以今天我就結(jié)合自己這些年趟過的坑把SpringBoot JPA分頁查詢的幾種典型場景掰開揉碎了講清楚。從最簡單的無查詢條件分頁到帶固定條件的Query分頁再到最靈活也最考驗功底的Specification動態(tài)分頁。我會重點說清楚每種方式的應(yīng)用場景、背后的原理、怎么寫以及為什么這么寫特別是那些官方文檔不會告訴你的性能陷阱和實用技巧。2. 基礎(chǔ)搭建你的Repository和實體準備好了嗎在開始玩轉(zhuǎn)各種分頁姿勢之前得先把舞臺搭好。這里假設(shè)我們有一個經(jīng)典的User用戶實體和一個對應(yīng)的UserRepository。這是所有后續(xù)操作的基石。2.1 實體定義與Repository接口首先是User實體類。我習(xí)慣用Data省去getter/setter但用Entity和Id標明JPA身份。注意CreationTimestamp和UpdateTimestamp它們能自動管理時間字段非常方便。import lombok.Data; import org.hibernate.annotations.CreationTimestamp; import org.hibernate.annotations.UpdateTimestamp; import javax.persistence.*; import java.time.LocalDateTime; Data Entity Table(name sys_user) // 指定表名避免使用關(guān)鍵字或符合命名規(guī)范 public class User { Id GeneratedValue(strategy GenerationType.IDENTITY) private Long id; Column(nullable false, unique true, length 50) private String username; Column(nullable false, length 100) private String email; private Integer age; Column(name dept_id) // 關(guān)聯(lián)部門ID private Long departmentId; Enumerated(EnumType.STRING) private UserStatus status UserStatus.ACTIVE; // 狀態(tài)枚舉 CreationTimestamp private LocalDateTime createTime; UpdateTimestamp private LocalDateTime updateTime; public enum UserStatus { ACTIVE, INACTIVE, LOCKED } }注意這里我特意將表名指定為sys_user字段departmentId映射為dept_id。在實際項目中數(shù)據(jù)庫表名和字段名往往有自己的一套規(guī)范如蛇形命名法與Java的駝峰命名不同。使用Table和Column注解顯式聲明映射關(guān)系能避免很多因命名約定不一致導(dǎo)致的“表或列不存在”的坑。特別是當數(shù)據(jù)庫由DBA或歷史系統(tǒng)設(shè)計時這個習(xí)慣能救你一命。接下來是UserRepository接口。它繼承JpaRepository立刻就能獲得一堆開箱即用的方法包括我們待會要用到的分頁查詢魔法。import org.springframework.data.domain.Page; import org.springframework.data.domain.Pageable; import org.springframework.data.jpa.repository.JpaRepository; import org.springframework.data.jpa.repository.JpaSpecificationExecutor; import org.springframework.stereotype.Repository; Repository public interface UserRepository extends JpaRepositoryUser, Long, JpaSpecificationExecutorUser { // 后續(xù)的各種查詢方法將在這里定義 }關(guān)鍵點在于這個接口同時繼承了JpaRepository和JpaSpecificationExecutor。JpaRepository提供了基礎(chǔ)的CRUD和簡單查詢方法例如findAll(Pageable pageable)。JpaSpecificationExecutor這是支持動態(tài)查詢的核心。它提供了findAll(Specification spec, Pageable pageable)等方法允許我們以編程方式構(gòu)建復(fù)雜的查詢條件。如果你確定后續(xù)會有動態(tài)查詢需求在一開始就把它加上是成本最低、最明智的做法。否則等到需要時再回來改接口、改所有相關(guān)Service那才叫一個麻煩。2.2 理解Pageable與Page分頁的核心抽象Spring Data JPA 的分頁圍繞兩個核心接口Pageable和Page。在寫代碼前必須搞懂它們是什么。Pageable分頁請求它代表前端或調(diào)用方發(fā)出的分頁指令。包含三個核心信息頁碼 (Page Number)從0開始計數(shù)。第1頁是page0。每頁大小 (Page Size)一頁顯示多少條記錄。排序 (Sort)可選。按照哪些字段升序(ASC)還是降序(DESC)排列。在Controller中我們通常這樣接收一個Pageable對象GetMapping(/users) public PageUser getUsers(PageableDefault(size 10, sort createTime, direction Sort.Direction.DESC) Pageable pageable) { return userService.getUsers(pageable); }PageableDefault注解可以指定默認值防止前端沒傳參數(shù)。你也可以直接使用PageRequest.of(page, size, sort)來手動創(chuàng)建。PageT分頁響應(yīng)它代表一次分頁查詢的結(jié)果不僅僅包含當前頁的數(shù)據(jù)列表(content)還包含豐富的分頁元數(shù)據(jù)content: ListT當前頁的數(shù)據(jù)。totalElements: long總記錄數(shù)滿足條件的總條數(shù)。totalPages: int總頁數(shù)。number: int當前頁碼0-based。size: int每頁大小。numberOfElements: int當前頁實際元素數(shù)量最后一頁可能不滿。一系列判斷方法isFirst(),isLast(),hasNext(),hasPrevious()等。為什么是Page而不是簡單的List因為前端分頁組件如Ant Design ProTable、ElementUI Table通常需要知道總條數(shù)來計算總頁數(shù)、顯示“共XXX條”等信息。如果你只返回一個List前端要么無法顯示完整分頁要么需要額外請求一次count查詢造成性能浪費。Page對象一次性封裝了數(shù)據(jù)和元信息是前后端協(xié)作的標準做法。3. 場景一最簡單的分頁——無任何查詢條件這是最基礎(chǔ)的場景適用于后臺管理系統(tǒng)中“展示所有數(shù)據(jù)”的列表頁。實現(xiàn)起來簡單到令人發(fā)指因為JPA已經(jīng)幫你全做好了。3.1 實現(xiàn)方式直接調(diào)用JpaRepository的內(nèi)置方法在你的UserRepository中你不需要寫任何方法。因為繼承自JpaRepository它已經(jīng)擁有了findAll(Pageable pageable)方法。在Service層直接調(diào)用即可Service RequiredArgsConstructor // Lombok注解自動注入final字段的repository public class UserService { private final UserRepository userRepository; public PageUser getAllUsers(Pageable pageable) { // 就這么簡單一行代碼 return userRepository.findAll(pageable); } }然后在Controller中調(diào)用這個Service方法返回PageUser給前端。3.2 原理解析與SQL觀察雖然代碼簡單但了解背后發(fā)生了什么很重要。打開SQL日志spring.jpa.show-sqltrue你會看到兩條SQL語句-- 1. 查詢總條數(shù) SELECT COUNT(*) FROM sys_user; -- 2. 查詢當前頁數(shù)據(jù)并應(yīng)用了排序 SELECT * FROM sys_user ORDER BY create_time DESC LIMIT 10 OFFSET 0;這里有一個至關(guān)重要的性能知識點JPA或者說其實現(xiàn)Hibernate在執(zhí)行分頁查詢時總是會先執(zhí)行一條COUNT(*)查詢來獲取總記錄數(shù)以便填充Page對象中的totalElements。無論你當前查的是第幾頁這條COUNT查詢都會發(fā)生。這意味著什么如果你的sys_user表有1000萬條數(shù)據(jù)SELECT COUNT(*) FROM sys_user可能會成為一個非常慢的操作即使在有索引的情況下對于超大規(guī)模數(shù)據(jù)COUNT依然有成本。這就是為什么在數(shù)據(jù)量極大的列表頁產(chǎn)品經(jīng)理或架構(gòu)師有時會要求“不做總數(shù)統(tǒng)計只做‘加載更多’”。因為COUNT查詢可能成為性能瓶頸。那么如何避免COUNT查詢?nèi)绻愦_定不需要總條數(shù)和總頁數(shù)只需要當前頁的數(shù)據(jù)Spring Data JPA 提供了返回Slice的API。Slice只包含當前頁數(shù)據(jù)和是否有下一頁的標記不執(zhí)行COUNT查詢。// Repository中定義 SliceUser findAllBy(Pageable pageable); // Service中調(diào)用 SliceUser userSlice userRepository.findAllBy(pageable);Slice適用于移動端無限滾動加載的場景。但在經(jīng)典的后臺管理系統(tǒng)表格分頁中前端組件通常依賴總條數(shù)所以Page仍然是默認和主流的選擇。了解這個區(qū)別能在性能敏感的場景下做出正確決策。4. 場景二帶固定查詢條件的分頁——Query注解的兩種寫法當你的查詢條件固定時比如“查詢所有狀態(tài)為ACTIVE的用戶”使用Query注解是清晰直觀的選擇。Query有兩種寫法JPQL面向?qū)ο蠛驮鶶QLNative Query。4.1 使用JPQL推薦JPQLJava Persistence Query Language是JPA的標準查詢語言它操作的是實體和屬性而不是數(shù)據(jù)庫表和列。這種方式是數(shù)據(jù)庫無關(guān)的換數(shù)據(jù)庫如MySQL換PostgreSQL通常不用改代碼。在UserRepository中添加方法public interface UserRepository extends JpaRepositoryUser, Long, JpaSpecificationExecutorUser { // 使用JPQL:status是命名參數(shù) Query(SELECT u FROM User u WHERE u.status :status) PageUser findByStatus(Param(status) User.UserStatus status, Pageable pageable); // 更復(fù)雜的例子多條件固定查詢 Query(SELECT u FROM User u WHERE u.status :status AND u.age :minAge AND u.departmentId :deptId) PageUser findActiveUsersInDeptAboveAge(Param(status) User.UserStatus status, Param(deptId) Long deptId, Param(minAge) Integer minAge, Pageable pageable); }為什么推薦JPQL類型安全:status參數(shù)綁定的是UserStatus枚舉類型編譯器能進行類型檢查減少運行時錯誤?？梢浦残圆灰蕾囂囟〝?shù)據(jù)庫的SQL方言。面向?qū)ο笾苯邮褂脤嶓w類名(User)和屬性名(status)更符合Java程序員的思維。使用時的坑點參數(shù)綁定必須使用Param如果方法參數(shù)名和JPQL中的參數(shù)名一致在Spring Boot 2.x版本中可以省略Param。但為了代碼清晰和兼容性我強烈建議始終顯式使用Param注解。分頁參數(shù)Pageable必須放在最后這是Spring Data JPA的約定Pageable以及Sort參數(shù)總是方法的最后一個參數(shù)。4.2 使用原生SQL需謹慎有時候查詢非常復(fù)雜涉及數(shù)據(jù)庫特定的函數(shù)或優(yōu)化JPQL可能無法表達這時就需要用到原生SQL。public interface UserRepository extends JpaRepositoryUser, Long, JpaSpecificationExecutorUser { Query(value SELECT * FROM sys_user u WHERE u.dept_id :deptId AND u.status :status, countQuery SELECT COUNT(*) FROM sys_user u WHERE u.dept_id :deptId AND u.status :status, nativeQuery true) PageUser findUsersByDeptAndStatusNative(Param(deptId) Long deptId, Param(status) String status, // 注意原生SQL參數(shù)通常是基本類型或String Pageable pageable); }注意看這里多了一個countQuery屬性。這是原生SQL分頁查詢的關(guān)鍵為什么需要countQuery當nativeQuery true時Spring Data JPA無法像解析JPQL那樣自動從你的查詢語句中推導(dǎo)出計算總數(shù)的SQL。如果你不提供countQueryJPA會嘗試做一件很“蠢”的事情把你的主查詢語句包裝成SELECT COUNT(*) FROM (你的原生SQL) AS count_table。對于簡單的SQL這可能沒問題。但一旦你的SQL包含GROUP BY,UNION或者某些數(shù)據(jù)庫如Oracle不支持子查詢的特定語法這個自動生成的countQuery就會直接報錯。所以使用原生SQL分頁的最佳實踐是永遠顯式地提供countQuery。這個countQuery應(yīng)該是一個高效、只用于計數(shù)的簡化版查詢。例如如果主查詢有很多JOIN和字段countQuery通常可以去掉不必要的JOIN和SELECT字段只關(guān)注COUNT和核心的WHERE條件這能顯著提升性能。原生SQL的缺點喪失數(shù)據(jù)庫可移植性SQL語法綁定特定數(shù)據(jù)庫。類型不安全參數(shù)和結(jié)果映射需要自己保證正確性。容易導(dǎo)致SQL注入雖然使用Param綁定參數(shù)是安全的但如果你錯誤地使用了字符串拼接來構(gòu)建SQL風(fēng)險就來了。絕對不要這樣做什么情況下該用原生SQL我的經(jīng)驗是除非遇到明確的性能瓶頸或者必須使用某個數(shù)據(jù)庫特有的高級功能如MySQL的ON DUPLICATE KEY UPDATEPostgreSQL的窗口函數(shù)等否則優(yōu)先使用JPQL。JPQL在99%的場景下都夠用且更安全、更干凈。5. 場景三動態(tài)查詢條件的王者——Specification前面兩種方式適用于條件固定的場景。但真實業(yè)務(wù)中更多的是動態(tài)查詢用戶在前端表格的多個篩選框里組合查詢比如“查找部門ID為1或2狀態(tài)為活躍年齡在20到30之間并且用戶名包含‘張’的用戶”。這種if-else套娃式的查詢用Query就力不從心了。這時就該Specification登場了。Specification是JPA Criteria API的Spring Data封裝它允許你以編程的、類型安全的方式動態(tài)構(gòu)建查詢條件。5.1 Specification基礎(chǔ)一個Predicate工廠Specification接口只有一個方法Predicate toPredicate(RootT root, CriteriaQuery? query, CriteriaBuilder cb);你可以把它理解為一個生產(chǎn)Predicate查詢條件斷言的工廠。CriteriaBuildercb是你的工具包提供了equal,like,between,greaterThan等各種構(gòu)建條件的“工具”。5.2 實戰(zhàn)構(gòu)建一個復(fù)雜的動態(tài)查詢假設(shè)我們有這樣一個動態(tài)查詢需求對應(yīng)上面提到的例子。我們首先在Service層創(chuàng)建一個構(gòu)建Specification的方法Service public class UserService { // ... 其他代碼 public SpecificationUser buildSpecification(Long[] deptIds, User.UserStatus status, Integer minAge, Integer maxAge, String usernameLike) { return (root, query, cb) - { // 1. 初始化一個條件列表最終所有條件會進行AND連接 ListPredicate predicates new ArrayList(); // 2. 部門IDIN查詢 (deptId in (1, 2, ...)) if (deptIds ! null deptIds.length 0) { predicates.add(root.get(departmentId).in((Object[]) deptIds)); } // 3. 狀態(tài)精確匹配 if (status ! null) { predicates.add(cb.equal(root.get(status), status)); } // 4. 年齡范圍BETWEEN查詢 (age between minAge and maxAge) if (minAge ! null) { predicates.add(cb.ge(root.get(age), minAge)); // ge: greater than or equal to } if (maxAge ! null) { predicates.add(cb.le(root.get(age), maxAge)); // le: less than or equal to } // 5. 用戶名模糊查詢LIKE查詢 (username like %張%) if (StringUtils.hasText(usernameLike)) { // 注意like需要處理通配符。這里用cb.like并在參數(shù)兩側(cè)加% // 也可以使用cb.like(root.get(username), % usernameLike %) predicates.add(cb.like(root.get(username), % usernameLike %)); } // 6. 將所有條件用AND連接起來 return cb.and(predicates.toArray(new Predicate[0])); }; } // 使用Specification進行分頁查詢 public PageUser searchUsers(Long[] deptIds, User.UserStatus status, Integer minAge, Integer maxAge, String usernameLike, Pageable pageable) { SpecificationUser spec buildSpecification(deptIds, status, minAge, maxAge, usernameLike); return userRepository.findAll(spec, pageable); } }代碼解讀與技巧鏈式構(gòu)建每個條件判斷后將生成的Predicate加入一個List。這種方式邏輯清晰易于閱讀和調(diào)試。CriteriaBuilder的使用cb.equal用于等值cb.ge/cb.le用于范圍cb.like用于模糊匹配root.get(“age”)獲取實體屬性。這些方法都是類型安全的。cb.and最后用cb.and將列表中的所有條件合并為一個復(fù)合的AND條件。如果需要OR條件可以使用cb.or?？罩蹬袛噙@是動態(tài)查詢的核心。只有當前端傳了某個篩選值時才添加對應(yīng)的條件。這避免了WHERE 11這種不優(yōu)雅的寫法。5.3 更優(yōu)雅的構(gòu)建方式使用Specification工具類每次都手寫if判斷和cb.xxx比較繁瑣。Spring Data JPA社區(qū)和很多項目都提供了工具類來簡化構(gòu)建。這里介紹一種我個人常用的、清晰易懂的方式public class UserSpecifications { public static SpecificationUser departmentIn(Long[] deptIds) { return (root, query, cb) - deptIds ! null deptIds.length 0 ? root.get(departmentId).in((Object[]) deptIds) : null; // 返回nullSpecification會忽略這個條件 } public static SpecificationUser statusEqual(User.UserStatus status) { return (root, query, cb) - status ! null ? cb.equal(root.get(status), status) : null; } public static SpecificationUser ageBetween(Integer minAge, Integer maxAge) { return (root, query, cb) - { if (minAge null maxAge null) return null; if (minAge ! null maxAge ! null) { return cb.between(root.get(age), minAge, maxAge); } else if (minAge ! null) { return cb.ge(root.get(age), minAge); } else { return cb.le(root.get(age), maxAge); } }; } public static SpecificationUser usernameLike(String username) { return (root, query, cb) - StringUtils.hasText(username) ? cb.like(root.get(username), % username %) : null; } }然后在Service中可以像搭積木一樣組合這些Specificationpublic PageUser searchUsersWithSpec(Long[] deptIds, User.UserStatus status, Integer minAge, Integer maxAge, String usernameLike, Pageable pageable) { SpecificationUser spec Specification.where(UserSpecifications.departmentIn(deptIds)) .and(UserSpecifications.statusEqual(status)) .and(UserSpecifications.ageBetween(minAge, maxAge)) .and(UserSpecifications.usernameLike(usernameLike)); // Specification.where() 是Spring Data JPA 2.x提供的靜態(tài)方法用于鏈式調(diào)用 return userRepository.findAll(spec, pageable); }這種方式將每個查詢條件原子化復(fù)用性極高并且Specification.where().and().and()的鏈式調(diào)用非常優(yōu)雅代碼可讀性極強。5.4 性能陷阱與優(yōu)化聯(lián)表查詢與COUNT優(yōu)化陷阱一N1查詢與聯(lián)表如果你的User實體通過ManyToOne關(guān)聯(lián)了Department實體并且在查詢中需要department.name直接在Specification里root.fetch(“department”)可能會引發(fā)問題。// 可能導(dǎo)致笛卡爾積或數(shù)據(jù)重復(fù) SpecificationUser spec (root, query, cb) - { root.fetch(department, JoinType.LEFT); // 謹慎使用 // ... 添加其他條件 return cb.and(predicates); };在分頁查詢中急切抓取Eager Fetch關(guān)聯(lián)實體特別是一對多OneToMany時可能會導(dǎo)致結(jié)果集行數(shù)爆炸一對多關(guān)聯(lián)會使主表行數(shù)倍增影響分頁準確性。Spring Data JPA 的Page可能無法正確處理這種情況。性能問題即使是一對一OneToOne或多對一ManyToOne在數(shù)據(jù)量大時JOIN也可能變慢。優(yōu)化建議延遲加載Lazy是默認且推薦的方式。在需要關(guān)聯(lián)數(shù)據(jù)時比如在Thymeleaf模板或Jackson序列化時通過EntityGraph注解或在查詢方法上聲明抓取策略來按需加載。如果確定本次查詢一定需要關(guān)聯(lián)數(shù)據(jù)且關(guān)聯(lián)關(guān)系不復(fù)雜可以使用EntityGraph注解在Repository方法上這比在Specification中fetch更可控。對于極其復(fù)雜的聯(lián)表分頁查詢有時不得不回歸原生SQL并通過countQuery精心優(yōu)化計數(shù)語句。陷阱二COUNT查詢的性能正如在場景一提到的Specification分頁同樣會觸發(fā)COUNT查詢。對于復(fù)雜的動態(tài)查詢這個COUNT查詢可能和主查詢一樣復(fù)雜。優(yōu)化思路緩存總數(shù)對于一些更新不頻繁的維度表可以將總條數(shù)緩存起來如用Redis定期更新。近似計數(shù)對于超大數(shù)據(jù)表如果業(yè)務(wù)可以接受可以使用EXPLAIN語句獲取的近似行數(shù)或者數(shù)據(jù)庫的快速估值如MySQL的SHOW TABLE STATUS但這不精確。業(yè)務(wù)設(shè)計與產(chǎn)品溝通是否可以用“加載更多”代替?zhèn)鹘y(tǒng)分頁從而使用Slice避免COUNT。6. 綜合對比與選型指南學(xué)了這么多招式到底該用哪個這張表幫你快速決策特性/場景無查詢條件分頁 (findAll(Pageable))Query(JPQL)Query(Native SQL)Specification查詢條件無固定在注解中寫死固定但可使用數(shù)據(jù)庫特性動態(tài)運行時構(gòu)建代碼復(fù)雜度極簡簡單清晰中等需寫兩條SQL較復(fù)雜但結(jié)構(gòu)清晰類型安全高高JPQL基于實體低基于字符串和數(shù)據(jù)庫列高基于Criteria API數(shù)據(jù)庫移植性高高低綁定特定SQL方言高性能控制弱自動生成COUNT中等自動生成COUNT強可自定義COUNT查詢中等自動生成COUNT適用場景簡單列表全量展示條件固定的復(fù)雜查詢?nèi)鐖蟊肀仨毷褂脭?shù)據(jù)庫特有語法或函數(shù)的超復(fù)雜查詢、性能調(diào)優(yōu)后臺管理系統(tǒng)的動態(tài)篩選列表、搜索功能可維護性高高查詢邏輯集中中SQL散落需理解業(yè)務(wù)高條件可復(fù)用、組合學(xué)習(xí)成本低低中需懂SQL中高需理解Criteria API我的個人選型心得默認選擇Specification對于業(yè)務(wù)系統(tǒng)中的列表查詢90%的情況都是動態(tài)的。即使一開始條件簡單后期也極有可能增加。從一開始就用Specification構(gòu)建雖然初期代碼量稍多但后期擴展性最好。配合工具類代碼也很優(yōu)雅。QueryJPQL 用于穩(wěn)定且復(fù)雜的查詢有些查詢邏輯非常固定且復(fù)雜比如一個包含多個聚合、子查詢的統(tǒng)計報表。把它寫成JPQL放在Query里比用Specification拼湊更直觀也更容易被其他開發(fā)者理解。原生SQL是最后的武器不要輕易使用。只有當你確認JPQL無法實現(xiàn)如使用特殊的窗口函數(shù)或者通過SQL執(zhí)行計劃分析確認原生SQL能帶來數(shù)量級的性能提升時才考慮使用。并且一定要寫好countQuery。簡單列表直接用findAll如果就是一個“查看所有”的功能別想太多直接用findAll(Pageable)清晰明了。7. 進階讓分頁查詢?nèi)缁⑻硪淼膶嵱眉记烧莆樟嘶菊惺皆賮睃c“內(nèi)功心法”讓你的分頁查詢更健壯、更高效。7.1 全局分頁參數(shù)配置與合理化你肯定不想在每個Controller方法上都寫PageableDefault?？梢栽谂渲妙惱镌O(shè)置全局默認值Configuration public class WebConfig implements WebMvcConfigurer { Override public void addArgumentResolvers(ListHandlerMethodArgumentResolver resolvers) { PageableHandlerMethodArgumentResolver resolver new PageableHandlerMethodArgumentResolver(); // 設(shè)置默認頁碼為第一頁page0 resolver.setOneIndexedParameters(false); // 默認false即page0是第一頁。如果前端傳1表示第一頁設(shè)為true。 // 設(shè)置默認每頁大小 resolver.setFallbackPageable(PageRequest.of(0, 20)); // 設(shè)置前端可用的參數(shù)名默認就是page, size, sort resolver.setPageParameterName(page); resolver.setSizeParameterName(size); resolvers.add(resolver); } }更重要的是參數(shù)合理化防止前端傳一個size1000把你的數(shù)據(jù)庫拖垮。Bean public PageableHandlerMethodArgumentResolverCustomizer pageableCustomizer() { return resolver - { resolver.setMaxPageSize(100); // 每頁最大100條 resolver.setFallbackPageable(PageRequest.of(0, 20)); // 默認20條 }; }7.2 排序Sort的靈活處理Pageable包含了Sort。前端可以通過sortcreateTime,descsortusername,asc這樣的參數(shù)傳遞排序。 在Repository中你可以直接使用PageUser findAll(Pageable pageable); // 排序信息已在pageable中在Query中如果排序是固定的可以直接寫在JPQL里。如果是動態(tài)的JPQL本身不支持在ORDER BY后使用參數(shù)綁定但Spring Data JPA很聰明它會自動將Pageable中的Sort附加到生成的SQL之后。但是對于原生SQL(nativeQuerytrue)這個自動附加可能失效你需要手動處理排序這非常麻煩。這也是優(yōu)先使用JPQL的另一個原因。在Specification中排序也是由傳入的Pageable控制的你不需要在Specification內(nèi)部處理ORDER BY。7.3 投影Projection與DTO只返回需要的字段很多時候前端列表不需要實體的全部字段比如不需要password、token等敏感或大字段。全量查詢并傳輸是一種浪費。方案一使用接口投影定義一個接口只包含需要的getter方法public interface UserSimpleInfo { String getUsername(); String getEmail(); Integer getAge(); // 甚至可以關(guān)聯(lián)查詢部門名稱假設(shè)有部門實體 Value(#{target.department?.name}) // 使用SpEL注意處理null String getDepartmentName(); }在Repository中直接使用這個接口作為返回類型Query(SELECT u.username as username, u.email as email, u.age as age FROM User u WHERE u.status ACTIVE) PageUserSimpleInfo findActiveUsersSimple(Pageable pageable);這種方式查詢效率高網(wǎng)絡(luò)傳輸量小。但注意它返回的是代理對象不是實體不能直接用于更新操作。方案二使用類投影DTO定義一個普通的DTO類在Query中使用構(gòu)造函數(shù)表達式Query(SELECT new com.yourproject.dto.UserListDTO(u.username, u.email, d.name) FROM User u JOIN u.department d WHERE u.status :status) PageUserListDTO findActiveUsersWithDept(Param(status) UserStatus status, Pageable pageable);UserListDTO需要有一個匹配參數(shù)順序的構(gòu)造函數(shù)。這種方式更靈活DTO類可以包含業(yè)務(wù)邏輯。7.4 多數(shù)據(jù)源與讀寫分離下的分頁在微服務(wù)或復(fù)雜應(yīng)用中Repository可能指向不同的數(shù)據(jù)源。Spring Data JPA對多數(shù)據(jù)源的支持很成熟。關(guān)鍵點在于為每個數(shù)據(jù)源配置獨立的EntityManagerFactory和TransactionManager。將不同的Repository包放在不同的路徑下通過EnableJpaRepositories注解指定各自的basePackages和entityManagerFactoryRef。在讀寫分離場景下分頁查詢通常走從庫。你需要確保在Service方法上使用Transactional(readOnly true)注解。這不僅是一個語義提示一些數(shù)據(jù)庫驅(qū)動或連接池可能會據(jù)此將連接路由到只讀實例。你的數(shù)據(jù)庫中間件如ShardingSphere、MyCat或框架如Spring AbstractRoutingDataSource能正確根據(jù)readOnly標志進行路由。一個常見的坑在readOnlytrue的事務(wù)里如果你不小心調(diào)用了entityManager.merge()或試圖修改實體狀態(tài)會立刻拋出異常。這實際上是好事強制你遵守讀寫分離的規(guī)范。8. 避坑實錄那些年我踩過的分頁之坑理論說再多不如踩坑記得牢。分享幾個讓我debug到深夜的典型問題?？?Page接口的getContent()返回ListS與T不符導(dǎo)致序列化失敗當你使用投影如PageUserSimpleInfo時直接返回Page對象給Spring MVC的RestControllerSpring Boot默認使用Jackson序列化。有時會遇到類型擦除或Jackson無法推斷類型的問題。穩(wěn)妥的做法是在Controller層將其轉(zhuǎn)換為一個明確的、可序列化的分頁響應(yīng)體GetMapping(/users) public ApiPageResultUserSimpleInfo getUsers(Pageable pageable) { PageUserSimpleInfo page userService.findUsers(pageable); // 自定義的響應(yīng)封裝類 return ApiPageResult.success(page); }ApiPageResult可以包含data,total,page,size等字段這樣前端對接也更規(guī)范?？?Specification中Path獲取錯誤導(dǎo)致的IllegalArgumentException// 錯誤示例屬性名拼寫錯誤或不存在 predicates.add(cb.equal(root.get(departId), deptId)); // 正確應(yīng)為 departmentId這種錯誤在編譯期不會報錯只在運行時拋出IllegalArgumentException: Unable to locate Attribute with the the given name。建議使用字符串常量或枚舉來定義屬性名或者利用IDE的自動補全功能避免手滑。坑3Query中JPQL的UPDATE/DELETE操作忘記加ModifyingQuery(UPDATE User u SET u.status :newStatus WHERE u.id :id) void updateStatus(Param(id) Long id, Param(newStatus) UserStatus newStatus); // 這樣執(zhí)行會報錯必須加上Modifying注解告訴Spring Data這是一個修改操作需要事務(wù)。Modifying Transactional // 通常也需要事務(wù)注解 Query(UPDATE User u SET u.status :newStatus WHERE u.id :id) int updateStatus(Param(id) Long id, Param(newStatus) UserStatus newStatus);坑4分頁查詢在LEFT JOIN后數(shù)據(jù)變少或重復(fù)這是SQLJOIN的經(jīng)典問題不是JPA的bug。當主表如User左連接一個子表如Order一個用戶有多個訂單分頁查詢LIMIT 10是在連接后的結(jié)果集上進行的。如果一個用戶有3個訂單他會在結(jié)果集中出現(xiàn)3次這可能導(dǎo)致該用戶“占用”了3個名額其他用戶可能被擠到下一頁。總用戶數(shù)統(tǒng)計不準。解決方案對于需要分頁的主查詢盡量避免一對多關(guān)系的JOIN。如果必須關(guān)聯(lián)考慮以下策略使用DISTINCTSELECT DISTINCT u FROM User u LEFT JOIN u.orders o ...。但這可能影響性能。分兩步查詢先分頁查詢出用戶ID列表不JOIN再根據(jù)ID列表查詢出完整的用戶及其關(guān)聯(lián)數(shù)據(jù)。這就是常說的“先查ID再查數(shù)據(jù)”模式。使用子查詢在WHERE子句中使用子查詢來過濾而不是直接JOIN?？?Page對象在序列化時的循環(huán)引用如果實體間有雙向關(guān)聯(lián)如User中有ListOrderOrder中有User并且沒有用JsonIgnore或JsonManagedReference/JsonBackReference處理將PageUser直接返回給JSON序列化時可能會陷入死循環(huán)導(dǎo)致棧溢出或返回巨大而無用的JSON。解決方案永遠為實體類的雙向關(guān)聯(lián)關(guān)系配置Jackson注解來切斷循環(huán)或者更推薦的是在Controller層返回專用的DTO/VO而不是實體本身。這不僅是解決循環(huán)引用的問題更是API設(shè)計的最佳實踐——控制輸出隱藏內(nèi)部細節(jié)。