Cómo devolver los resultados de una API por páginas, con orden y filtros, usando lo que ya trae Spring Data: un parámetro Pageable en el controlador y un Page como respuesta.
También te puede interesar
Por qué paginar
Devolver la tabla completa en una sola respuesta funciona con 20 productos; con 200,000 tumba al servidor, a la base y al celular del cliente. Paginar es entregar los resultados en trozos: «dame la página 3, de 20 en 20, ordenada por precio». Spring Data lo resuelve con dos tipos: Pageable (lo que pides) y Page (lo que recibes, con los datos y el total).
El repositorio y el controlador
Todos los métodos de JpaRepository que devuelven listas tienen una versión con Pageable, y tus consultas derivadas también la aceptan con solo agregar el parámetro:
package com.ejemplo.catalogo;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.jpa.repository.JpaRepository;
public interface ProductoRepository extends JpaRepository<Producto, Long> {
Page<Producto> findByNombreContainingIgnoreCase(String texto, Pageable pagina);
}En el controlador, Spring llena el Pageable con los parámetros page, size y sort de la dirección. @PageableDefault define qué pasa si no vienen:
package com.ejemplo.catalogo;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.domain.Sort;
import org.springframework.data.web.PageableDefault;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class ProductoController {
private final ProductoRepository repo;
public ProductoController(ProductoRepository repo) {
this.repo = repo;
}
@GetMapping("/productos")
public Page<Producto> pagina(@RequestParam(defaultValue = "") String texto,
@PageableDefault(size = 5, sort = "id") Pageable pagina) {
return repo.findByNombreContainingIgnoreCase(texto, pagina);
}
}Falta un ajuste. Si devuelves el Page tal cual, funciona, pero Spring Data escribe en el registro: «Serializing PageImpl instances as-is is not supported, meaning that there is no guarantee about the stability of the resulting JSON structure!». Es decir, la forma del JSON podría cambiar en una versión futura y romper a tus clientes. Una línea en application.properties le pide a Spring Data un formato estable, con los datos en content y la información de la página aparte, en page:
spring.application.name=catalogo spring.jpa.open-in-view=false spring.data.web.pageable.serialization-mode=via-dto spring.jpa.show-sql=true
La base de este ejemplo tiene 23 productos de prueba. Usamos jq para mostrar solo los nombres y la información de la página:
terminal$ curl -s "localhost:8080/productos" | jq -c '{nombres: [.content[].nombre], page}'
{"nombres":["Funda 1","Funda 2","Cable 3","Funda 4","Funda 5"],"page":{"size":5,"number":0,"totalElements":23,"totalPages":5}}
$ curl -s "localhost:8080/productos?page=4" | jq -c '{nombres: [.content[].nombre], page}'
{"nombres":["Cable 21","Funda 22","Funda 23"],"page":{"size":5,"number":4,"totalElements":23,"totalPages":5}}
$ curl -s "localhost:8080/productos?size=3&sort=precio,desc" | jq -c '[.content[] | {nombre, precio}]'
[{"nombre":"Cable 21","precio":427.00},{"nombre":"Funda 10","precio":420.00},{"nombre":"Funda 20","precio":390.00}]
$ curl -s "localhost:8080/productos?texto=cable&size=4&page=1" | jq -c '{nombres: [.content[].nombre], page}'
{"nombres":["Cable 15","Cable 18","Cable 21"],"page":{"size":4,"number":1,"totalElements":7,"totalPages":2}}Las páginas empiezan en 0, no en 1: la página 4 es la quinta, la última, y trae los 3 productos que sobran. El bloque page le dice al cliente cuántas páginas hay, para dibujar los botones de «siguiente» y «anterior». sort=precio,desc ordena por cualquier atributo de la entidad, y el filtro por texto se combina con la paginación sin escribir nada más.
El SQL que se ejecuta
Con spring.jpa.show-sql=true se ven las sentencias. Para la primera petición, Hibernate hizo dos consultas: la de los datos, con fetch first (la forma estándar de SQL del LIMIT; las páginas siguientes agregan offset), y un count para saber el total:
registro de la aplicación (la primera petición)Hibernate: select p1_0.id,p1_0.nombre,p1_0.precio from producto p1_0 where upper(p1_0.nombre) like upper(?) escape '\' order by p1_0.id fetch first ? rows only Hibernate: select count(p1_0.id) from producto p1_0 where upper(p1_0.nombre) like upper(?) escape '\'
En la última página (la 4) no hubo count: trajo menos filas que el tamaño pedido, así que Spring Data ya pudo calcular el total sin preguntar.
Con millones de filas, ese count puede ser lo más lento. Si no necesitas el total, devuelve un Slice en vez de un Page: Spring Data pide una fila de más para saber si hay página siguiente y se ahorra el conteo.
Pon un límite al tamaño de página. Sin él, cualquiera puede pedir size=1000000. Spring Data ya trae uno de fábrica:
terminal$ curl -s "localhost:8080/productos?size=1000" | jq -c '.page'
{"size":1000,"number":0,"totalElements":23,"totalPages":1}Pedimos 1,000 y entregó 23 en una sola página porque no hay más; con más datos, el máximo de fábrica es 2,000 por página. Bájalo con spring.data.web.pageable.max-page-size=100.
Cada proyecto de esta página se compiló con Spring Boot 4.2.0, Java 25 (Temurin 25.0.5.1) y Maven 3.10.1 en un contenedor limpio y sin red, se arrancó y se probó con las peticiones de curl que ves; las respuestas y los registros están copiados de esa ejecución.