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
Pageableen el método del repositorio y devuelvePage<T>: Spring Data añadeLIMIT/OFFSET, elORDER BYy una consultacountpara el total. En un controlador,Pageablese rellena solo desde la URL (?page=0&size=5&sort=titulo,desc). En Spring Boot 4, devuelve elPageserializado 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.Pageconserva 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 unPageImpldirectamente produce un JSON con detalles internos que pueden cambiar entre versiones, y Spring lo desaconseja con un aviso. ConVIA_DTOobtienes la forma establecontent+pagede arriba.
Parámetros de la URL
| Parámetro | Ejemplo | Significado |
|---|---|---|
page | page=2 | Número de página, desde 0 |
size | size=20 | Elementos por página |
sort | sort=titulo,desc | Campo 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 elementos | Sí | No |
Consulta count adicional | Sí | No |
| Sabe si hay página siguiente | Sí | Sí |
| Úsalo para | Tablas 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.
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.