問い合わせ一覧が数百件になり、「全部取得してから画面で20件ずつ切る」実装が苦しくなった。Spring Data JPAなら、Repositoryへ Pageable を渡して取得範囲を限定できます。
ただし私は、PageRequest.of(page, size) を置くだけでは完成としません。ページ番号の0始まり、件数の上限、同日時データの順序まで決めます。これを曖昧にすると、最初のページが一つずれたり、ページを移動したとき同じ行が見えたりします。さらに、page × sizeをJPAへ渡せる範囲に制限し、空ページの200と入力拒否の400を分けます。以下は JDK 17、Spring Boot 3.5.16、Spring Data JPA 3.5系で試せる架空の問い合わせ一覧です。総件数を表示するか迷う場合は、同じ条件でPageとSliceが発行するSQLを比較する例へ進めます。
Controllerの引数をPageableにして上限を設定すると、範囲外の件数も補正して200で進む場合があります。同じpageとsizeで400・200を比べる実習で、契約に合う実装を選べます。
実行用サンプル
作成日時が同じ未対応3件と、除外する完了済み1件で、ページ境界・入力制限・返却するhasNextを確かめます。JDK 17とMaven 3.9系でmvn testを実行すると、この専用サンプルの15件を確認できます。ZIPにはController・Repository・Entity・テスト全文・pom.xml・設定・READMEを収録しています。下のSQLもsql/offset-shift.sqlに同梱しました。本文では、必要なファイルを開閉して読めます。
最初のページは0、表示上は1
PageRequest.of(0, 20) は最初の20件を要求します。次ページは PageRequest.of(1, 20) です。画面に「1ページ目」と出したいなら、表示時だけ (long) page + 1 にします。
URLの page | Repositoryへ渡す値 | 画面の表示 |
|---|---|---|
| 0 | 0 | 1ページ目 |
| 1 | 1 | 2ページ目 |
URLも1始まりにしたいなら、入口で1を引いて内部の0始まりへ変換します。画面だけ1始まり、APIだけ0始まりのような混在を放置せず、公開するURLの契約を先に決めてください。
RepositoryとControllerの最小例
Inquiry は id、title、createdAt、status を持つこのサンプルのJPA Entity、Status.OPEN は一覧へ出す未対応の状態とします。Spring Bootアプリには spring-boot-starter-data-jpa とDBドライバーを追加します。
InquiryRepository.java の全文
package info.syachiku.audit;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.jpa.repository.JpaRepository;
interface InquiryRepository extends JpaRepository<Inquiry, Long> {
Page<Inquiry> findByStatus(Status status, Pageable pageable);
}Controllerでは、利用者が自由に size=1000000 を指定できないようにします。また並び順は外部パラメータをそのままプロパティ名へ通さず、画面の仕様として固定します。
InquiryController.java の全文
package info.syachiku.audit;
import java.util.List;
import org.springframework.data.domain.PageRequest;
import org.springframework.data.domain.Sort;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;
record InquiryRow(Long id, String title) {}
record InquiryPage(List<InquiryRow> items, int page, int size,
long totalElements, int totalPages, boolean hasNext) {}
@RestController
class InquiryController {
private final InquiryRepository repository;
InquiryController(InquiryRepository repository) {
this.repository = repository;
}
@GetMapping("/inquiries")
InquiryPage list(@RequestParam(defaultValue = "0") int page,
@RequestParam(defaultValue = "20") int size) {
if (page < 0 || size < 1 || size > 50
|| (long) page * size > Integer.MAX_VALUE) {
throw new ResponseStatusException(HttpStatus.BAD_REQUEST,
"pageまたはsizeが範囲外です");
}
Sort order = Sort.by(Sort.Direction.DESC, "createdAt")
.and(Sort.by(Sort.Direction.DESC, "id"));
var result = repository.findByStatus(Status.OPEN,
PageRequest.of(page, size, order));
var rows = result.getContent().stream()
.map(i -> new InquiryRow(i.getId(), i.getTitle()))
.toList();
return new InquiryPage(rows, page, size, result.getTotalElements(),
result.getTotalPages(), (long) page + 1 < result.getTotalPages());
}
}残りの実行用ファイルは次のとおりです。InquiryとStatusもこの専用ZIPの型を使い、既存プロジェクトのEntityへ置き換えた結果と混同しないでください。
src/main/java/info/syachiku/audit/Inquiry.java の全文
package info.syachiku.audit;
import jakarta.persistence.*;
import java.time.Instant;
@Entity
public class Inquiry {
@Id
private Long id;
private String title;
@Enumerated(EnumType.STRING)
private Status status;
private Instant createdAt;
protected Inquiry() {
}
Inquiry(Long id, String title, Status status, Instant createdAt) {
this.id = id;
this.title = title;
this.status = status;
this.createdAt = createdAt;
}
Long getId() {
return id;
}
String getTitle() {
return title;
}
}src/main/java/info/syachiku/audit/Status.java の全文
package info.syachiku.audit;
enum Status {
OPEN,
CLOSED
}src/main/java/info/syachiku/audit/PageableInputApplication.java の全文
package info.syachiku.audit;
import java.time.Instant;
import java.util.List;
import org.springframework.boot.ApplicationRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
@SpringBootApplication
public class PageableInputApplication {
public static void main(String[] args) {
SpringApplication.run(PageableInputApplication.class, args);
}
// The executable sample starts with only four fixed, in-memory rows.
@Bean
ApplicationRunner seedSample(InquiryRepository repository) {
return arguments -> {
Instant time = Instant.parse("2026-11-01T00:00:00Z");
repository.saveAll(List.of(
new Inquiry(1L, "問い合わせ1", Status.OPEN, time),
new Inquiry(2L, "問い合わせ2", Status.OPEN, time),
new Inquiry(3L, "問い合わせ3", Status.OPEN, time),
new Inquiry(4L, "完了済み", Status.CLOSED, time)));
System.out.println("SEED_READY open=3 closed=1");
};
}
}pom.xml の全文
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>3.5.16</version><relativePath/></parent>
<groupId>info.syachiku.samples</groupId><artifactId>pageable-input-boundary-2289</artifactId><version>1.0.0</version>
<properties><java.version>17</java.version><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><junit-jupiter.version>5.12.2</junit-jupiter.version></properties>
<dependencies>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-data-jpa</artifactId></dependency>
<dependency><groupId>com.h2database</groupId><artifactId>h2</artifactId><scope>runtime</scope></dependency>
<dependency>
<groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope>
<exclusions>
<exclusion><groupId>org.mockito</groupId><artifactId>mockito-core</artifactId></exclusion>
<exclusion><groupId>org.mockito</groupId><artifactId>mockito-junit-jupiter</artifactId></exclusion>
</exclusions>
</dependency>
</dependencies>
<build><plugins>
<plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin>
<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>3.5.6</version></plugin>
</plugins></build>
</project>src/main/resources/application.properties の全文
spring.datasource.url=jdbc:h2:mem:pageable-input-boundary
spring.jpa.hibernate.ddl-auto=create-drop
spring.jpa.open-in-view=false
spring.jpa.properties.hibernate.generate_statistics=true
spring.jpa.properties.hibernate.default_batch_fetch_size=0
logging.level.org.hibernate.engine.internal.StatisticalLoggingSessionEventListener=OFFREADME.md の全文
# Pageableの入力境界をDB検索前に確認する(2289)
JDK17、Maven3.9系。Spring Boot3.5.16 / Spring Framework6.2.19 / Spring Data Commons3.5.13 / Hibernate6.6.53.Final / H2 2.3.232 / JUnit5.12.2。
```sh
mvn test
mvn package
java -jar target/pageable-input-boundary-2289-1.0.0.jar
```
最初の実行では依存取得のネットワークが必要です。検証はJava17.0.8/Maven3.9.16の既存キャッシュでoffline実行しています。完全に空のキャッシュからの取得は未確認です。
## APIとデータ
`GET /inquiries?page=0&size=2`。pageは0始まり、既定0/20。sizeは1..50。createdAt DESC、id DESC。同時刻のOPEN3件(ID1,2,3)とCLOSED1件(ID4)だけを、起動時のメモリH2へ入れます。GETは更新しません。外部DB/API・認証は使いません。
```json
{"items":[{"id":3,"title":"問い合わせ3"},{"id":2,"title":"問い合わせ2"}],"page":0,"size":2,"totalElements":3,"totalPages":2,"hasNext":true}
```
2ページ目(page=1)はID1だけ、page=2は200で空配列・totalElements=3・hasNext=falseです。範囲外だから400にする仕様ではありません。
## 入力ガードと巨大境界
`page<0 || size<1 || size>50 || (long) page*size>Integer.MAX_VALUE`をRepository呼出し前に確認し、違反は400。pageとsizeがintでも積がintを超えるので、掛け算の前にlongへ変換します。`(long)(page*size)`はintでオーバーフローした後の変換になり、このガードには使えません。
| page | size | long offset | 結果 |
|---|---|---|---|
| 42949672 | 50 | 2147483600 | 200・空・total3・hasNext=false |
| 42949673 | 50 | 2147483650 | 400・SQL準備0 |
| 2147483647 | 1 | 2147483647 | 200・空・total3・hasNext=false |
| 2147483647 | 50 | 107374182350 | 400・SQL準備0 |
採用版のPageImpl.hasNextはintのpage+1比較を使うため、最大pageでtrueへ反転することを初回試験で確認しました。このJSONでは`(long) page + 1 < result.getTotalPages()`を使い、通常の中間ページtrue/最終ページfalseと巨大範囲外falseを保ちます。依存ライブラリを変更していません。
## テストの範囲
元のInquiryControllerTest2件は内容を変えず収録し、同時刻ID降順・最終/範囲外・size51を確認します。InquiryBoundaryTest13件は、負page/size0/51/積の上限超過5件、intに変換できない2件、許容する巨大offset2件、size1/50の2件、既定値1件、空DB1件を確認します。旧2件と合わせて15件です。テストは小さな固定データだけです。
拒否を確認する試験では、seedを完了してからHibernate Statistics.clear()、リクエスト、prepareStatementCount=0を確認します。これは当該リクエストがSQLを準備しないという意味で、起動/seedまでDBを使わないわけではありません。Mockitoへ置き換えていません。
```sh
python3 scripts/verify_http.py target/pageable-input-boundary-2289-1.0.0.jar
```
Python3の実HTTP確認は、127.0.0.1の空きポートでJARを起動し、既定/通常範囲外/巨大境界の200・400とJSONを見て終了します。別途JARを起動しておく必要はありません。スクリプトの--baselineは旧固定JARを1件だけ比較する検証用で、通常の修正版確認では指定しません。
## SQLで途中追加のページずれを確認する
`sql/offset-shift.sql`は記事本文のSQLと同じものです。JUnitの静的ページ境界とは別に、途中で新しい行が増えたときのoffsetとkeysetを比較します。空のH2メモリDBで1回だけ実行し、最初104/103、途中追加後offsetの次ページ103/102、keysetの次ページ102/101を確認します。
```sh
java -cp "$HOME/.m2/repository/com/h2database/h2/2.3.232/h2-2.3.232.jar" org.h2.tools.Shell -url 'jdbc:h2:mem:page-shift' -user sa -sql "$(cat sql/offset-shift.sql)"
```
Shellを終了するとメモリDBは消えます。このSQLはJPAのInquiryテーブルを操作しません。少数データで正しい値を観測したもので、数千万件のデータ生成・深いoffsetの性能測定・運用DBでの性能保証を行ったわけではありません。
## 既存配布との関係
旧spring/audit-behaviorの共有モジュールから必要な型と元の2テストだけを抽出。Entity/Repository/Statusと既存2テストはbyte不変。Controllerの変更はoffsetガードとhasNextの安全な算出だけです。Spring Web/JPA/H2の実構成を保持します。旧共有モジュール・その固定リンク・他記事用のコードは変更しません。
ZIPはソース・設定・JUnit・SQL・手順・HTTP確認・LICENSEを収録し、依存JAR、class、実行JAR、個人設定は含みません。createdAt DESC に id DESC を加えると、同じ時刻でも順序が決まります。その順序が決まっていても、1ページ目と2ページ目の間に行が追加されると、オフセットが指す位置は変わります。
同じ並び順で1行追加し、2ページ目のIDを比べる
検証用の空のH2データベースで次のSQLを上から実行します。最初の取得は [104, 103]。同じ日時の105を先頭側へ追加してから2行飛ばすと [103, 102] になり、103が重複します。専用ZIPのJUnitはAPIの入力境界を確認します。途中の追加による位置ずれは、同梱のsql/offset-shift.sqlにある下のSQLで別に再現します。
CREATE TABLE demo_page_shift (
id BIGINT PRIMARY KEY,
created_at TIMESTAMP NOT NULL
);
INSERT INTO demo_page_shift VALUES
(101, TIMESTAMP '2026-11-01 00:00:00'),
(102, TIMESTAMP '2026-11-01 00:00:00'),
(103, TIMESTAMP '2026-11-01 00:00:00'),
(104, TIMESTAMP '2026-11-01 00:00:00');
SELECT id FROM demo_page_shift
ORDER BY created_at DESC, id DESC FETCH FIRST 2 ROWS ONLY;
INSERT INTO demo_page_shift VALUES (105, TIMESTAMP '2026-11-01 00:00:00');
SELECT id FROM demo_page_shift
ORDER BY created_at DESC, id DESC OFFSET 2 ROWS FETCH NEXT 2 ROWS ONLY;
SELECT id FROM demo_page_shift
WHERE created_at < TIMESTAMP '2026-11-01 00:00:00'
OR (created_at = TIMESTAMP '2026-11-01 00:00:00' AND id < 103)
ORDER BY created_at DESC, id DESC FETCH FIRST 2 ROWS ONLY;最後の検索は、1ページ目の末尾で見た (created_at, id) より後ろだけを取得するため、この追加では [102, 101] から続けられます。カーソルを使う場合は、並び順に使う日時とIDを両方持ちます。途中で行が削除されたり、並べ替えに使う値が変更されたりすると結果も変わるので、閲覧開始時の集合を固定する要件は別途決めます。 Spring Data 3.5のキーセットスクロール
入力の比較実習
Controller引数をPageableにすると、範囲外でも200になる場合がある
クライアントに入力ミスを直してもらうAPIで、Controllerの引数をPageableへ変更する場面です。GET /inquiries?page=1&size=51は、自分で上限50を検証すると400。Pageableの上限を50に設定すると、50件に補正して200になります。
JDK 17とMaven 3.9系で、ZIPを展開しpom.xmlのある場所でmvn clean testを実行します。Spring Boot 3.5.16・Spring Data Commons 3.5.13で、同じ7入力を3設定で比べるMockMvcテスト21件を収録。採用されたpage・sizeと、後続処理に進む回数を確認します。実習の後続処理は、受け取ったページ条件をJSONにします。
手動で検証する版では、生のpageとsizeを受け取り、範囲内ならPageRequestを作ります。Pageable版は、Spring Dataがリクエストを読み取って組み立てた値を受け取ります。以下は配布コードのControllerメソッドの抜粋です。
@GetMapping("/inquiries")
PageSelection list(@RequestParam(defaultValue = "0") int page,
@RequestParam(defaultValue = "20") int size) {
if (page < 0 || size < 1 || size > 50
|| (long) page * size > Integer.MAX_VALUE) {
throw new ResponseStatusException(HttpStatus.BAD_REQUEST,
"pageまたはsizeが範囲外です");
}
return search.run(PageRequest.of(page, size));
}@GetMapping("/inquiries")
PageSelection list(Pageable pageable) {
return search.run(pageable);
}| 同じ入力 | 手動で 検証 | Pageable 既定 | Pageable 上限50 |
|---|---|---|---|
page=1 | 200(1, 2) | 200(1, 2) | 200(1, 2) |
page=-1 | 400 | 200(0, 2) | 200(0, 2) |
page=1 | 400 | 200(1, 20) | 200(1, 20) |
page=1 | 400 | 200(1, 51) | 200(1, 50) |
page=1 | 400 | 200(1, 2000) | 200(1, 50) |
この構成の既定のページサイズは20、上限は2000です。spring.data.web.pageable.max-page-size=50は上限だけを設定するので、size=0はどちらのPageable設定でも20に補正されます。負のpageは0になります。
レビューで決めるのは、「大きすぎる値を送り直してもらう」か「最大件数に揃えて結果を返す」かです。400を返す契約なら、Pageableが補正する前に元の値を受け取って検証します。補正して200を返す契約なら、採用した件数と検索処理を1回呼ぶことをテストで残します。
0件と最終ページを先に決める
size=2ならpage=0のIDは3と2、page=1は1、page=2は空です。総件数は3、総ページは2で、最後とその先はhasNext=falseです。データがないことは入力エラーにしません。一方、page<0・size<1・size>50、JPAへ渡せない取得開始位置は400にします。同じ作成日時でも第2ソートキーのidで順序を決めます。
InquiryControllerTest.java の全文
package info.syachiku.audit;
import java.time.Instant;
import java.util.List;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.servlet.MockMvc;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
@SpringBootTest
@AutoConfigureMockMvc
class InquiryControllerTest {
@Autowired
private InquiryRepository repository;
@Autowired
private MockMvc mvc;
@BeforeEach
void seed() {
repository.deleteAll();
Instant time = Instant.parse("2026-11-01T00:00:00Z");
repository.saveAll(List.of(
new Inquiry(1L, "問い合わせ1", Status.OPEN, time),
new Inquiry(2L, "問い合わせ2", Status.OPEN, time),
new Inquiry(3L, "問い合わせ3", Status.OPEN, time),
new Inquiry(4L, "完了済み", Status.CLOSED, time)));
}
@Test
void 同時刻のOPENをID降順で返し最終ページと範囲外を区別する() throws Exception {
mvc.perform(get("/inquiries").param("page", "0").param("size", "2"))
.andExpect(status().isOk())
.andExpect(jsonPath("$.items.length()").value(2))
.andExpect(jsonPath("$.items[0].id").value(3))
.andExpect(jsonPath("$.items[1].id").value(2))
.andExpect(jsonPath("$.totalElements").value(3))
.andExpect(jsonPath("$.totalPages").value(2))
.andExpect(jsonPath("$.hasNext").value(true));
mvc.perform(get("/inquiries").param("page", "1").param("size", "2"))
.andExpect(status().isOk())
.andExpect(jsonPath("$.items.length()").value(1))
.andExpect(jsonPath("$.items[0].id").value(1))
.andExpect(jsonPath("$.hasNext").value(false));
mvc.perform(get("/inquiries").param("page", "2").param("size", "2"))
.andExpect(status().isOk())
.andExpect(jsonPath("$.items").isEmpty())
.andExpect(jsonPath("$.totalElements").value(3))
.andExpect(jsonPath("$.totalPages").value(2))
.andExpect(jsonPath("$.hasNext").value(false));
}
@Test
void 取得件数が51なら400を返す() throws Exception {
mvc.perform(get("/inquiries").param("size", "51"))
.andExpect(status().isBadRequest());
}
}上のInquiryControllerTestは、並び順・最後・その先の空ページとsize上限を確認する2件です。次のInquiryBoundaryTestでは、省略値・sizeの両端・巨大offset・intへの変換失敗・0件を追加して確認します。合計は15件です。拒否ケースのSQL件数は、事前データ登録の後で統計をリセットして測っています。
src/test/java/info/syachiku/audit/InquiryBoundaryTest.java の全文
package info.syachiku.audit;
import jakarta.persistence.EntityManagerFactory;
import java.time.Instant;
import java.util.List;
import org.hibernate.SessionFactory;
import org.hibernate.stat.Statistics;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;
import static org.junit.jupiter.api.Assertions.*;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
@SpringBootTest
@AutoConfigureMockMvc
class InquiryBoundaryTest {
@Autowired InquiryRepository repository;
@Autowired MockMvc mvc;
@Autowired EntityManagerFactory entityManagerFactory;
private Statistics statistics;
@BeforeEach
void seedBeforeClearingStatistics() {
repository.deleteAll();
Instant time = Instant.parse("2026-11-01T00:00:00Z");
repository.saveAll(List.of(
new Inquiry(1L, "問い合わせ1", Status.OPEN, time),
new Inquiry(2L, "問い合わせ2", Status.OPEN, time),
new Inquiry(3L, "問い合わせ3", Status.OPEN, time),
new Inquiry(4L, "完了済み", Status.CLOSED, time)));
statistics = entityManagerFactory.unwrap(SessionFactory.class).getStatistics();
assertTrue(statistics.isStatisticsEnabled());
statistics.clear();
}
@ParameterizedTest(name = "reject before DB: page={0}, size={1}")
@CsvSource({"-1,2", "0,0", "0,51", "42949673,50", "2147483647,50"})
void rejectsInvalidBoundsWithoutPreparingSql(int page, int size) throws Exception {
mvc.perform(get("/inquiries").param("page", String.valueOf(page))
.param("size", String.valueOf(size)))
.andExpect(status().isBadRequest());
assertEquals(0L, statistics.getPrepareStatementCount());
System.out.printf("REJECT page=%d size=%d status=400 sql=%d%n",
page, size, statistics.getPrepareStatementCount());
}
@ParameterizedTest(name = "int conversion: page={0}, size={1}")
@CsvSource({"2147483648,1", "0,2147483648"})
void intOverflowTextFailsBeforeControllerAndDatabase(String page, String size)
throws Exception {
var result = mvc.perform(get("/inquiries").param("page", page).param("size", size))
.andExpect(status().isBadRequest()).andReturn();
assertInstanceOf(MethodArgumentTypeMismatchException.class, result.getResolvedException());
assertEquals(0L, statistics.getPrepareStatementCount());
}
@ParameterizedTest(name = "accepted large offset: page={0}, size={1}")
@CsvSource({"42949672,50,1", "2147483647,1,3"})
void acceptsRepresentableOffsetsAndReportsAnEmptyPage(int page, int size, int pages)
throws Exception {
mvc.perform(get("/inquiries").param("page", String.valueOf(page))
.param("size", String.valueOf(size)))
.andExpect(status().isOk())
.andExpect(jsonPath("$.items").isEmpty())
.andExpect(jsonPath("$.page").value(page))
.andExpect(jsonPath("$.size").value(size))
.andExpect(jsonPath("$.totalElements").value(3))
.andExpect(jsonPath("$.totalPages").value(pages))
.andExpect(jsonPath("$.hasNext").value(false));
}
@ParameterizedTest(name = "size endpoint: {0}")
@CsvSource({"1,1,3,true", "50,3,1,false"})
void acceptsBothSizeEndpoints(int size, int items, int pages, boolean next)
throws Exception {
mvc.perform(get("/inquiries").param("size", String.valueOf(size)))
.andExpect(status().isOk())
.andExpect(jsonPath("$.items.length()").value(items))
.andExpect(jsonPath("$.items[0].id").value(3))
.andExpect(jsonPath("$.page").value(0))
.andExpect(jsonPath("$.totalElements").value(3))
.andExpect(jsonPath("$.totalPages").value(pages))
.andExpect(jsonPath("$.hasNext").value(next));
}
@Test
void omissionUsesPageZeroAndSizeTwenty() throws Exception {
mvc.perform(get("/inquiries"))
.andExpect(status().isOk())
.andExpect(jsonPath("$.page").value(0))
.andExpect(jsonPath("$.size").value(20))
.andExpect(jsonPath("$.items.length()").value(3))
.andExpect(jsonPath("$.items[0].id").value(3))
.andExpect(jsonPath("$.items[1].id").value(2))
.andExpect(jsonPath("$.items[2].id").value(1))
.andExpect(jsonPath("$.totalElements").value(3))
.andExpect(jsonPath("$.totalPages").value(1))
.andExpect(jsonPath("$.hasNext").value(false));
}
@Test
void emptyDatabaseStillReturnsAValidEmptyPage() throws Exception {
repository.deleteAll();
statistics.clear();
mvc.perform(get("/inquiries"))
.andExpect(status().isOk())
.andExpect(jsonPath("$.items").isEmpty())
.andExpect(jsonPath("$.totalElements").value(0))
.andExpect(jsonPath("$.totalPages").value(0))
.andExpect(jsonPath("$.hasNext").value(false));
}
}
たとえば全41件、1ページ20件なら page=0 と page=1 が20件ずつ、page=2 が1件です。page=3 は空になります。getTotalPages() は3、最後のページの hasNext() は false です。0件なら items=[]、totalElements=0 として画面に「該当なし」を出します。
ページ番号が最終ページを超えても、取得開始位置をJPAに渡せる範囲なら、この例はHTTP 200と空の一覧を返します。たとえば配布テストの3件に対する page=2・size=2 では items=[]、totalElements=3、hasNext=false です。404にするか空一覧を返すかはAPIの契約として決めます。
旧コードはpageとsizeをそれぞれ検査するだけだったため、page=42949673&size=50でHTTP 500になりました。どちらもintに入りますが、取得開始位置page × sizeは2,147,483,650となり、JPAへ渡せるInteger.MAX_VALUE(2,147,483,647)を超えます。単なる空ページではなく、Page offset exceeds Integer.MAX_VALUEとなる境界です。掲載Controllerと専用ZIPには、この掛け算の検査を組み込みました。
修正版は|| (long) page * size > Integer.MAX_VALUEをControllerの入力チェックへ入れ、Repositoryへ進む前に400を返します。掛け算の前にlongへ広げるのが要点です。(long) (page * size)では、先にintで計算されます。42949673 * 50はそこで-2,147,483,646へあふれるため、後からlongにしても上限超過を検出できません。(long) page * sizeなら2,147,483,650のまま比較できます。
表は横にスクロールできます。
| page | size | longで計算したoffset | 修正後のHTTP |
|---|---|---|---|
| 42949672 | 50 | 2147483600 | 200・空一覧 |
| 42949673 | 50 | 2147483650 | 400 |
| 2147483647 | 1 | 2147483647 | 200・空一覧 |
| 2147483647 | 50 | 107374182350 | 400 |
配布ZIPを展開し、pom.xmlのある場所でmvn spring-boot:runを実行します。http://localhost:8080/inquiries?page=42949672&size=50は200の空一覧、page=42949673へ変えると400です。表の200の2行は、未対応3件に対してitems=[]・totalElements=3・hasNext=falseになります。400の行はAPI呼出し中のSQLが0件であることもテストで確認しています。大きいoffsetでの検索速度を保証する検証ではありません。
画面が「次へ」を出す判定にitems.size() == sizeを使うと、最終ページがちょうど20件だった場合に間違えます。取得件数だけで判断せず、ページ番号と総ページ数を使います。
さらに採用版のSpring Data Commons 3.5.13では、PageImpl.hasNext()の内部でページ番号にintの1を加えます。page=2147483647&size=1はoffset上限内ですが、この加算があふれ、空一覧でもtrueになりました。そこで今回のレスポンスは(long) page + 1 < result.getTotalPages()でhasNextを返します。上限検査の掛け算とは別に、次ページ判定の加算もlongで行います。この極端な境界の挙動は、採用版と同じテストで確認してください。
Page を選ぶ前に件数表示の要否を考える
問い合わせ一覧に「全3件」「1/2ページ」を表示するなら、総件数・総ページ数を持つ Page を選びます。「もっと見る」だけの一覧なら、表示する行と次のページの有無を返す Slice で足ります。すでにAPIが totalElements や totalPages を返している場合は、画面や呼び出し元の利用状況を確かめてから変更します。
PageとSliceを同じ条件で実行し、COUNT SQLを比べる
同じ時刻に登録された問い合わせを4件用意します。検索対象の OPEN は ID 1・2・3、条件から外れる CLOSED は ID 4 です。両メソッドに同じ Pageable を渡し、作成日時の降順、同日時ならIDの降順で2件ずつ取得します。
- 先頭をPageで取得IDは3、2。次ページあり、総件数は3。データ取得1回と、総件数を数えるSQL1回。
- 先頭をSliceで取得IDは3、2。次ページあり。データ取得1回で、件数を数えるSQLは0回。
- 末尾をPageで取得IDは1。次ページなし、総件数は3。前の2件と取得した1件から総件数が分かり、この条件では件数を数えるSQLは0回。
Slice は、指定した件数より1件多く取得できるかで次のページを判定します。この例では内部で3件目を確認し、呼び出し元には先頭2件を返します。Page の件数SQLも毎回出るとは限りません。最後のページなど、取得範囲と結果の件数から総件数を決められる場合は省かれます。
テストの実測です。select は COUNT を含むSELECT文の合計です。Repositoryを呼び出した間のSQLを記録するため、テストデータの登録は数えません。? はバインド変数で、取得上限の値はこのログには出ません。
PAGE last ids=[1] hasNext=false totalElements=3 select=1 count=0
SQL select i1_0.id,i1_0.created_at,i1_0.status from inquiry i1_0 where i1_0.status=? order by i1_0.created_at desc,i1_0.id desc offset ? rows fetch first ? rows only
PAGE first ids=[3, 2] hasNext=true totalElements=3 select=2 count=1
SQL select i1_0.id,i1_0.created_at,i1_0.status from inquiry i1_0 where i1_0.status=? order by i1_0.created_at desc,i1_0.id desc fetch first ? rows only
SQL select count(i1_0.id) from inquiry i1_0 where i1_0.status=?
SLICE first ids=[3, 2] hasNext=true totalElements=なし select=1 count=0
SQL select i1_0.id,i1_0.created_at,i1_0.status from inquiry i1_0 where i1_0.status=? order by i1_0.created_at desc,i1_0.id desc fetch first ? rows only2つのメソッドで変えているのは、戻り値の種類です。検索条件の status と並び順を共通にしているため、返る行とSQLの差を切り分けられます。
package example.pageable;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.domain.Slice;
import org.springframework.data.jpa.repository.JpaRepository;
interface InquiryRepository extends JpaRepository<Inquiry, Long> {
Page<Inquiry> findByStatus(Inquiry.Status status, Pageable pageable);
Slice<Inquiry> findSliceByStatus(Inquiry.Status status, Pageable pageable);
}PageSliceComparisonTest.java の全文を表示する
package example.pageable;
import java.time.Instant;
import java.util.List;
import java.util.regex.Pattern;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
import org.springframework.boot.test.autoconfigure.orm.jpa.TestEntityManager;
import org.springframework.data.domain.PageRequest;
import org.springframework.data.domain.Pageable;
import org.springframework.data.domain.Slice;
import org.springframework.data.domain.Sort;
import static example.pageable.Inquiry.Status.CLOSED;
import static example.pageable.Inquiry.Status.OPEN;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;
@DataJpaTest(showSql = false, properties =
"spring.jpa.properties.hibernate.session_factory.statement_inspector=example.pageable.SqlCapture")
class PageSliceComparisonTest {
private static final Pattern SELECT = Pattern.compile("^\\s*select\\b", Pattern.CASE_INSENSITIVE);
private static final Pattern COUNT = Pattern.compile("^\\s*select\\s+count\\s*\\(", Pattern.CASE_INSENSITIVE);
private static final Sort ORDER = Sort.by(Sort.Direction.DESC, "createdAt", "id");
@Autowired
private InquiryRepository repository;
@Autowired
private TestEntityManager entityManager;
@BeforeEach
void seedRowsBeforeRecordingSql() {
Instant at = Instant.parse("2026-11-01T00:00:00Z");
entityManager.persist(new Inquiry(1, OPEN, at));
entityManager.persist(new Inquiry(2, OPEN, at));
entityManager.persist(new Inquiry(3, OPEN, at));
entityManager.persist(new Inquiry(4, CLOSED, at));
entityManager.flush();
entityManager.clear();
}
@Test
void fullFirstPageNeedsAnExtraCountButSliceDoesNot() {
Pageable first = PageRequest.of(0, 2, ORDER);
var page = SqlCapture.capture(() -> repository.findByStatus(OPEN, first));
var slice = SqlCapture.capture(() -> repository.findSliceByStatus(OPEN, first));
assertEquals(List.of(3L, 2L), ids(page.result()));
assertEquals(ids(page.result()), ids(slice.result()));
assertTrue(page.result().hasNext());
assertTrue(slice.result().hasNext());
assertEquals(3, page.result().getTotalElements());
assertSql(page.statements(), 2, 1);
assertSql(slice.statements(), 1, 0);
print("PAGE first", page.result(), page.result().getTotalElements(), page.statements());
print("SLICE first", slice.result(), "なし", slice.statements());
}
@Test
void partialLastPageCanInferItsTotalWithoutCounting() {
Pageable last = PageRequest.of(1, 2, ORDER);
var page = SqlCapture.capture(() -> repository.findByStatus(OPEN, last));
assertEquals(List.of(1L), ids(page.result()));
assertFalse(page.result().hasNext());
assertEquals(3, page.result().getTotalElements());
assertSql(page.statements(), 1, 0);
print("PAGE last", page.result(), page.result().getTotalElements(), page.statements());
}
private static List<Long> ids(Slice<Inquiry> result) {
return result.getContent().stream().map(Inquiry::id).toList();
}
private static long countByPattern(List<String> sql, Pattern pattern) {
return sql.stream().filter(statement -> pattern.matcher(statement).find()).count();
}
private static void assertSql(List<String> sql, int selects, int counts) {
assertEquals(selects, sql.size());
assertEquals(selects, countByPattern(sql, SELECT));
assertEquals(counts, countByPattern(sql, COUNT));
}
private static void print(String label, Slice<Inquiry> result, Object total, List<String> sql) {
System.out.printf("%s ids=%s hasNext=%s totalElements=%s select=%d count=%d%n",
label, ids(result), result.hasNext(), total,
countByPattern(sql, SELECT), countByPattern(sql, COUNT));
sql.forEach(statement -> System.out.println(" SQL " + statement));
}
}SqlCapture.java の全文を表示する
package example.pageable;
import java.util.ArrayList;
import java.util.List;
import java.util.function.Supplier;
import org.hibernate.resource.jdbc.spi.StatementInspector;
public final class SqlCapture implements StatementInspector {
private static final ThreadLocal<List<String>> CURRENT_CALL = new ThreadLocal<>();
@Override
public String inspect(String sql) {
List<String> statements = CURRENT_CALL.get();
if (statements != null) {
statements.add(sql);
}
return sql;
}
static <T> Execution<T> capture(Supplier<T> query) {
List<String> statements = new ArrayList<>();
CURRENT_CALL.set(statements);
try {
return new Execution<>(query.get(), List.copyOf(statements));
} finally {
CURRENT_CALL.remove();
}
}
record Execution<T>(T result, List<String> statements) {
}
}レビューで「一覧が遅いからSliceにした」と説明するなら、まず画面が総件数を使っているかを確認します。そのうえで先頭と最終ページを同じデータで実行し、行の順序と hasNext() が同じこと、意図したSQLが減ったことを確認します。このサンプルで計っているのはSQLの回数です。応答時間は、実際のDBとデータ件数で別途確認します。
実装後は、0件、1件、20件、21件、同じ createdAt の複数件で画面を確認します。最後にSQLログで、想定した件数制限と並び順が実際のDB問い合わせへ反映されているかを見てください。
ログに出た COUNT が何を数えているか読めなかったら、『スッキリわかるSQL入門 第4版』の第3章「操作する行の絞り込み」と第6章「集計とグループ化」を参照してください。同じ条件で「条件に合う行を2件だけ返すSQL」と「条件に合う行をすべて数えるSQL」を書いて比べると、一覧の2件と総件数の3件が別の情報だと分かります。
スッキリわかるSQL入門 第4版
SELECTから集計・結合まで、SQLの基本を一冊で学ぶ。
Javaコードだけでは解決できない検索不具合を理解する土台になります。SQLを初めて触る新人向けです。
- SQLを基礎から学びたい
- 検索条件やJOINを理解したい
当サイトはAmazonアソシエイト・プログラムの参加者です。価格・在庫・配送条件はAmazonでご確認ください。
