Introducción#

Imagina que tu aplicación intenta cargar 80,000 registros de una vez. El resultado: respuestas lentas, consumo excesivo de memoria y una aplicación que se vuelve inutilizable. Este problema es más común de lo que parece. La solución está en ordenar y paginar los datos. En lugar de cargar miles de registros, trabajamos con pequeños fragmentos ordenados que el usuario puede navegar fácilmente. En este artículo, aprenderemos cómo implementar ordenamiento y paginación en Spring Boot usando JPA.

Ordenamiento con Sort#

Sort es una clase de Spring Data que permite definir criterios de ordenamiento para las consultas. Puede usarse de forma independiente o combinada con paginación. Veamos cómo implementarlo paso a paso cuando solo necesitamos ordenar sin paginar:

Implementación#

Paso 1: Repositorio#

1
@Repository
2
public interface IEmployeeRepository extends JpaRepository<Employee, Long> {
3
    // Spring Data JPA automáticamente soporta Sort
4
    List<Employee> findAll(Sort sort);
5

6
    // También funciona con métodos personalizados
7
    List<Employee> findByDepartment(String department, Sort sort);
8
}

Paso 2: Servicio#

1
@Service
2
public class EmployeeService {
3
    private final IEmployeeRepository employeeRepository;
4

5
    public EmployeeService(EmployeeRepository employeeRepository) {
6
        this.employeeRepository = employeeRepository;
7
    }
8

9
    public List<Employee> getAllEmployeesSorted(Sort sort) {
10
        return employeeRepository.findAll(sort);
11
    }
12
}

Paso 3: Controller con @SortDefault#

1
@RestController
2
@RequestMapping("/api/employees")
3
public class EmployeeController {
4
    private final EmployeeService employeeService;
5

6
    public EmployeeController(EmployeeService employeeService) {
7
        this.employeeService = employeeService;
8
    }
9

10
    @GetMapping("/all")
11
    public List<Employee> getAllEmployeesSorted(
12
        @SortDefault(sort = "lastName", direction = Sort.Direction.ASC) Sort sort
13
    ) {
14
        return employeeService.getAllEmployeesSorted(sort);
15
    }
16
}

TIP
@SortDefault define valores por defecto cuando el cliente no envía parámetros de ordenamiento.

Uso desde el cliente#

El cliente puede especificar criterios de ordenamiento en las peticiones HTTP:

1
# Ordenar por apellido (usa el valor por defecto)
2
GET /api/employees/all
3

4
# Ordenar por salario descendente
5
GET /api/employees/all?sort=salary,desc
6

7
# Ordenar por múltiples campos
8
GET /api/employees/all?sort=department,asc&sort=lastName,asc
9

10
# Sin especificar dirección (por defecto es ASC)
11
GET /api/employees/all?sort=firstName

Ordenamiento Programático#

También podemos crear el ordenamiento directamente en el código:

1
@GetMapping("/top-earners")
2
public List<Employee> getTopEarners() {
3
    // Crear Sort con ordenamiento personalizado
4
    Sort sort = Sort.by("salary").descending()
5
                    .and(Sort.by("lastName").ascending());
6

7
    return employeeService.getAllEmployeesSorted(sort);
8
}

Paginación y Ordenamiento#

Pageable es la interfaz de Spring Data JPA que integra paginación y ordenamiento simultáneamente. En lugar de cargar todos los registros, dividimos los datos en páginas (por ejemplo, 50 registros por página) y los ordenamos según criterios específicos. Los resultados se devuelven en un objeto Page<T> que contiene tanto los datos solicitados como información útil sobre la paginación:

content: Lista de elementos de la página actual
totalElements: Total de elementos en la base de datos
totalPages: Total de páginas disponibles
number: Número de página actual (comienza en 0)
size: Tamaño de la página
first y last: Indicadores de primera y última página

Implementación#

Paso 1: Repositorio#

1
@Repository
2
public interface IEmployeeRepository extends JpaRepository<Employee, Long> {
3
    // Spring Data JPA automáticamente soporta Pageable
4
    Page<Employee> findAll(Pageable pageable);
5

6
    // También funciona con métodos personalizados
7
    Page<Employee> findByDepartment(String department, Pageable pageable);
8
}

TIP
No necesitas implementar estos métodos. Spring Data JPA genera automáticamente las consultas SQL con LIMIT y OFFSET basándose en el objeto Pageable.

Paso 2: Servicio#

1
@Service
2
public class EmployeeService {
3
    private final IEmployeeRepository employeeRepository;
4

5
    public EmployeeService(IEmployeeRepository employeeRepository) {
6
        this.employeeRepository = employeeRepository;
7
    }
8

9
    public Page<Employee> getAllEmployees(Pageable pageable) {
10
        return employeeRepository.findAll(pageable);
11
    }
12

13
    public Page<Employee> getEmployeesByDepartment(String department, Pageable pageable) {
14
        return employeeRepository.findByDepartment(department, pageable);
15
    }
16
}

Paso 3: Controller con @PageableDefault#

1
@RestController
2
@RequestMapping("/api/employees")
3
public class EmployeeController {
4
    private final EmployeeService employeeService;
5

6
    public EmployeeController(EmployeeService employeeService) {
7
        this.employeeService = employeeService;
8
    }
9

10
    @GetMapping
11
    public Page<Employee> getEmployees(
12
        @PageableDefault(
13
            page = 0,           // Página por defecto
14
            size = 50,          // Tamaño por defecto
15
            sort = "lastName",  // Campo por defecto para ordenar
16
            direction = Sort.Direction.ASC  // Dirección del ordenamiento
17
        ) Pageable pageable
18
    ) {
19
        return employeeService.getAllEmployees(pageable);
20
    }
21

22
    @GetMapping("/department/{department}")
23
    public Page<Employee> getEmployeesByDepartment(
24
        @PathVariable String department,
25
        @PageableDefault(size = 20, sort = "salary", direction = Sort.Direction.DESC) Pageable pageable
26
    ) {
27
        return employeeService.getEmployeesByDepartment(department, pageable);
28
    }
29
}

TIP
@PageableDefault define valores por defecto cuando el cliente no envía parámetros de paginación. La página comienza en 0 (primera página).

Uso desde el cliente#

El cliente puede combinar paginación y ordenamiento en las peticiones HTTP:

1
# Primera página con valores por defecto
2
GET /api/employees
3

4
# Segunda página (página 1) con 50 elementos
5
GET /api/employees?page=1&size=50
6

7
# Con ordenamiento
8
GET /api/employees?sort=salary,desc
9

10
# Múltiples criterios de ordenamiento
11
GET /api/employees?sort=department,asc&sort=salary,desc
12

13
# Paginación y ordenamiento juntos (tercera página con 25 elementos)
14
GET /api/employees?page=2&size=25&sort=salary,desc

Ordenamiento Programático con Paginación#

Podemos crear objetos Pageable con ordenamiento personalizado directamente en el código:

1
@GetMapping("/top-earners")
2
public Page<Employee> getTopEarners(
3
    @RequestParam(defaultValue = "0") int page,
4
    @RequestParam(defaultValue = "25") int size
5
) {
6
    // Crear Pageable con ordenamiento personalizado
7
    Pageable pageable = PageRequest.of(
8
        page,
9
        size,
10
        Sort.by("salary").descending()
11
            .and(Sort.by("lastName").ascending())
12
    );
13

14
    return employeeService.getAllEmployees(pageable);
15
}

Personalizando la Respuesta#

Cuando usamos Page<T> como tipo de retorno, Spring Boot serializa la respuesta con muchos metadatos que pueden ser innecesarios. Por eso se recomienda crear un record de response personalizado con solo los campos que necesitamos:

1
public record PageResponse<T>(
2
    List<T> content,
3
    int page,
4
    int size,
5
    long totalElements,
6
    int totalPages,
7
    boolean first,
8
    boolean last
9
) {
10
    public static <T> PageResponse<T> of(Page<T> page) {
11
        return new PageResponse<>(
12
            page.getContent(),
13
            page.getNumber(),
14
            page.getSize(),
15
            page.getTotalElements(),
16
            page.getTotalPages(),
17
            page.isFirst(),
18
            page.isLast()
19
        );
20
    }
21
}

Ejemplo de uso en el controller:

1
@GetMapping
2
public PageResponse<Employee> getEmployees(
3
    @PageableDefault(size = 50) Pageable pageable
4
) {
5
    Page<Employee> page = employeeService.getAllEmployees(pageable);
6
    return PageResponse.of(page);
7
}

Esto genera una respuesta limpia y con solo los datos necesarios:

1
{
2
  "content": [...],
3
  "page": 0,
4
  "size": 50,
5
  "totalElements": 80000,
6
  "totalPages": 1600,
7
  "first": true,
8
  "last": false
9
}

Manejo de Excepciones en el Ordenamiento#

Cuando el cliente intenta ordenar por un campo que no existe en la entidad, Spring lanza una PropertyReferenceException. Podemos capturar esta excepción y devolver un mensaje de error claro usando @RestControllerAdvice:

1
@RestControllerAdvice
2
public class GlobalExceptionHandler {
3
    @ExceptionHandler(PropertyReferenceException.class)
4
    public ProblemDetail handlePropertyReferenceException(PropertyReferenceException ex) {
5
        var problemDetail = ProblemDetail.forStatusAndDetail(
6
            HttpStatus.BAD_REQUEST,
7
            "Invalid property '" + ex.getPropertyName() + "' specified in request"
8
        );
9
        problemDetail.setTitle("Invalid Sort Field");
10
        return problemDetail;
11
    }
12
}

Ejemplo de petición que genera el error:

1
GET /api/employees?sort=invalidField,desc

Respuesta de error:

1
{
2
  "type": "about:blank",
3
  "title": "Invalid Sort Field",
4
  "status": 400,
5
  "detail": "Invalid property 'invalidField' specified in request"
6
}

NOTE
ProblemDetail es una clase de Spring que implementa el estándar RFC 7807 para representar errores en APIs REST.

Conclusión#

La paginación y el ordenamiento son técnicas fundamentales para construir aplicaciones Spring Boot escalables y con buen rendimiento. Con las herramientas que nos proporciona Spring Data JPA, implementar estas funcionalidades es sorprendentemente simple. Siguiendo estas prácticas, nuestras APIs podrán manejar millones de registros sin problemas, proporcionando respuestas rápidas y una excelente experiencia de usuario.