1・2・3ページのカードと安定した並び順を示す図。ページングの件数と順序を確認する

実装・エラー解決

Spring Data JPAでページングする方法|Pageableのページ番号・件数・並び順

問い合わせ一覧が数百件になり、「全部取得してから画面で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の pageRepositoryへ渡す値画面の表示
001ページ目
112ページ目

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=OFF
README.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
size=2
200(1, 2)200(1, 2)200(1, 2)
page=-1
size=2
400200(0, 2)200(0, 2)
page=1
size=0
400200(1, 20)200(1, 20)
page=1
size=51
400200(1, 51)200(1, 50)
page=1
size=2500
400200(1, 2000)200(1, 50)
200の下の括弧は、後続処理が受け取った (page, size)。200では1回、400では0回です。

この構成の既定のページサイズは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));
    }
}
OPEN3件を対象にDBを検索し、page=2・size=2では200と空一覧を返す。CLOSEDは除外。offset2,147,483,650はDB前で止め400を返す比較図。
検索対象はOPEN3件(CLOSEDは除外)。範囲内の空ページは200、不正なoffsetはDBへ渡す前に400で止める。

たとえば全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のまま比較できます。

表は横にスクロールできます。

pagesizelongで計算したoffset修正後のHTTP
42949672502147483600200・空一覧
42949673502147483650400
214748364712147483647200・空一覧
214748364750107374182350400

配布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 only

2つのメソッドで変えているのは、戻り値の種類です。検索条件の 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版」の表紙
商品画像:Amazon.co.jp
PR SQL初学者向け

スッキリわかるSQL入門 第4版

中山 清喬 (著), 飯田 理恵子 (著), 株式会社フレアリンク (監修)

SELECTから集計・結合まで、SQLの基本を一冊で学ぶ。

Javaコードだけでは解決できない検索不具合を理解する土台になります。SQLを初めて触る新人向けです。

  • SQLを基礎から学びたい
  • 検索条件やJOINを理解したい

当サイトはAmazonアソシエイト・プログラムの参加者です。価格・在庫・配送条件はAmazonでご確認ください。

参考資料

-実装・エラー解決
-