Artículo

Paginación con Pageable en Spring Boot y Spring Data JPA

Cómo paginar y ordenar resultados con Pageable y Page en Spring Data JPA y exponerlos en una API REST de Spring Boot 4, con el JSON real que devuelve.

En resumen: declara un parámetro Pageable en el método del repositorio y devuelve Page<T>: Spring Data añade LIMIT/OFFSET, el ORDER BY y una consulta count para el total. En un controlador, Pageable se rellena solo desde la URL (?page=0&size=5&sort=titulo,desc). En Spring Boot 4, devuelve el Page serializado como DTO (PagedModel) para tener un JSON estable. Probado con Spring Boot 4.1.2 y H2, con MockMvc.

Vídeo explicativo

En el repositorio

Cualquier JpaRepository ya tiene findAll(Pageable). Para consultas propias, añade el parámetro:

interface LibroRepository extends JpaRepository<Libro, Long> {
    Page<Libro> findByPaginasGreaterThan(int paginas, Pageable pageable);
}
Page<Libro> pagina = libros.findAll(PageRequest.of(1, 10, Sort.by("titulo").descending()));
System.out.println("Página " + pagina.getNumber() + " de " + pagina.getTotalPages()
        + ", total " + pagina.getTotalElements() + ", primero: " + pagina.getContent().get(0).getTitulo());

Con 23 libros guardados («Libro 01» … «Libro 23»):

Página 1 de 3, total 23, primero: Libro 13

Las páginas empiezan en 0: la página 1 es la segunda. Ordenando por título descendente, la primera página va de «Libro 23» a «Libro 14», y la segunda empieza en «Libro 13».

En el controlador

@SpringBootApplication
@EnableSpringDataWebSupport(pageSerializationMode = EnableSpringDataWebSupport.PageSerializationMode.VIA_DTO)
public class DemoApplication { ... }

record LibroDto(Long id, String titulo, int paginas) {}

@RestController
class LibroController {
    private final LibroRepository libros;

    LibroController(LibroRepository libros) {
        this.libros = libros;
    }

    // GET /libros?page=0&size=5&sort=titulo,desc
    @GetMapping("/libros")
    Page<LibroDto> listar(@RequestParam(defaultValue = "0") int minPaginas,
                          @PageableDefault(size = 10, sort = "titulo", direction = Sort.Direction.ASC) Pageable pageable) {
        return libros.findByPaginasGreaterThan(minPaginas, pageable)
                .map(l -> new LibroDto(l.getId(), l.getTitulo(), l.getPaginas()));
    }
}

Petición GET /libros?minPaginas=200&page=0&size=5&sort=paginas,desc. Respuesta real:

{
  "content": [
    {"id": 23, "titulo": "Libro 23", "paginas": 330},
    {"id": 22, "titulo": "Libro 22", "paginas": 320},
    {"id": 21, "titulo": "Libro 21", "paginas": 310},
    {"id": 20, "titulo": "Libro 20", "paginas": 300},
    {"id": 19, "titulo": "Libro 19", "paginas": 290}
  ],
  "page": {"size": 5, "number": 0, "totalElements": 13, "totalPages": 3}
}

Tres detalles de ese código:

  • .map(...) a un DTO. Page conserva los metadatos al transformar el contenido: no expongas entidades en la API.
  • @PageableDefault. Define tamaño y orden cuando el cliente no los envía.
  • VIA_DTO. Serializar un PageImpl directamente produce un JSON con detalles internos que pueden cambiar entre versiones, y Spring lo desaconseja con un aviso. Con VIA_DTO obtienes la forma estable content + page de arriba.

Parámetros de la URL

ParámetroEjemploSignificado
pagepage=2Número de página, desde 0
sizesize=20Elementos por página
sortsort=titulo,descCampo y dirección; se puede repetir para varios campos

Para limitar el tamaño máximo (que nadie pida size=100000): spring.data.web.pageable.max-page-size=100.

Page frente a Slice

Page<T>Slice<T>
Sabe el total de elementosSíNo
Consulta count adicionalSíNo
Sabe si hay página siguienteSíSí
Úsalo paraTablas con «página X de Y»Scroll infinito, tablas enormes

En tablas de millones de filas el count puede costar más que la propia consulta. Si no necesitas el total, devuelve Slice. Si además el OFFSET se vuelve lento en páginas profundas, la alternativa es paginar por clave (keyset): «dame 20 libros con id mayor que el último que vi».

Preguntas frecuentes

¿Cómo ordeno por un campo de una relación?

Con la ruta del campo: sort=autor.nombre,asc. Spring Data genera el join.

¿Funciona con @Query?

Sí. Añade Pageable como último parámetro; si la consulta tiene join complejos, indica también countQuery para que el total sea correcto.

¿Por qué totalElements no es el total de la tabla?

Porque cuenta los resultados de la consulta, con sus filtros. En el ejemplo, solo los 13 libros con más de 200 páginas.

¿Y para limitar sin paginar?

Usa findTop10By... o Limit. Lo tienes en limitar resultados en Spring Data JPA.

Sigue aprendiendo

Paginación, proyecciones y consultas eficientes se trabajan en el curso Spring Data JPA 4.1. Para la parte de API, crear una API REST con Spring Boot.

pageable paginación spring data jpa spring boot api rest page

Newsletter Semanal de Java

Cada viernes recibe lo más nuevo del ecosistema Java: frameworks, herramientas y mejores prácticas.

Sin spam. Cancela cuando quieras.

Compartir artículo