Understanding and Configuring Pagination Rationalization with MyBatis PageHelper in SpringBoot

Hello, I am sum Mo, a frontline backend developer who enjoys researching and documenting technical issues. This article focuses on pagination rationalization—a backend mechanism that automatically corrects unreasonable pagination parameters such as out‑of‑range page numbers, non‑positive page sizes, or excessively large page sizes.

Typical unreasonable cases include:

Requesting a page number beyond the total number of pages (e.g., requesting page 11 when only 10 pages exist). With rationalization enabled, the system returns the last page instead of an empty set.

Requesting a page number less than 1. The system adjusts it to page 1.

Requesting a page size of 0 or a negative number. The system may default to a sensible size, such as 10 items per page.

Requesting an excessively large page size (e.g., 1000 items). The system caps the size to a safe maximum, like 100 items.

Why enable pagination rationalization? Besides preventing server overload from huge page sizes, a front‑end bug can expose the need for it. The bug occurs when a user deletes the only record on the second page: the front‑end still requests page 2, receives an empty result, but the total count drops, causing the pagination component to think only one page remains. The UI then shows page 1 without data—a clear bug that must be fixed on the backend.

Bug Reproduction

The front‑end pagination component requires two parameters: total rows and rows per page. With 6 total rows and a page size of 5, there are two pages. Deleting the sole record on page 2 leads to the described inconsistency.

Bug Analysis

1. The front‑end requests http://localhost:8080/user/pageQuery?pageNum=2&pageSize=5 while page 2 still has one record.

2. After deleting that record, the front‑end again requests page 2, but the data set is now empty.

3. The total count has changed to 5, so the pagination component calculates only one page and switches to page 1, yet the query still targets page 2, resulting in no data.

This edge case demonstrates that the backend must handle pagination rationalization to keep the UI consistent.

Enabling Pagination Rationalization

If you use PageHelper, fixing the bug is as easy as adding two configuration lines:

pagehelper.helper-dialect=mysql
pagehelper.reasonable=true

These settings apply globally. For a single query, you can pass the true flag directly:

PageHelper.startPage(pageNumber, pageSize, true);

How the Configuration Works

The core implementation resides in com.github.pagehelper.Page . The setReasonable method adjusts the page number when it is less than or equal to zero, and the calculateStartAndEndRow method recomputes the start and end rows based on the corrected page number and page size.

public Page
setReasonable(Boolean reasonable) {
    if (reasonable == null) {
        return this;
    }
    this.reasonable = reasonable;
    // Pagination rationalization: automatically handle unreasonable page numbers
    if (this.reasonable && this.pageNum <= 0) {
        this.pageNum = 1;
        calculateStartAndEndRow();
    }
    return this;
}

private void calculateStartAndEndRow() {
    this.startRow = this.pageNum > 0 ? (this.pageNum - 1) * this.pageSize : 0;
    this.endRow = this.startRow + this.pageSize * (this.pageNum > 0 ? 1 : 0);
}

Other parts of the framework, such as PageInterceptor.intercept , integrate this logic into the query execution flow (illustrated by the accompanying diagram).

Understanding these internals gives confidence that enabling pagination rationalization is safe and effective, while also preparing you to troubleshoot any new issues that might arise.