Pageable 응답 DTO 규격(정렬·페이지 표준화)

Pageable 응답 DTO 규격(정렬·페이지 표준화)

페이지 응답이 API마다 제각각이면 프런트가 반복해서 어댑터를 작성해야 합니다.
Page<T>를 표준 DTO로 매핑해, 필수 메타와 정렬 정보를 통일합니다.

표준 응답 DTO

public record PageResponse<T>(List<T> content, Meta meta) {
  public static record Meta(int page, int size, long totalElements, int totalPages,
                            boolean first, boolean last, List<SortOrder> sort) {}
  public static record SortOrder(String property, String direction) {}
}

매핑 유틸

public static <T> PageResponse<T> of(Page<T> p) {
  List<PageResponse.SortOrder> s = p.getSort().stream()
    .map(o -> new PageResponse.SortOrder(o.getProperty(), o.getDirection().name()))
    .toList();
  PageResponse.Meta m = new PageResponse.Meta(p.getNumber(), p.getSize(),
      p.getTotalElements(), p.getTotalPages(), p.isFirst(), p.isLast(), s);
  return new PageResponse<T>(p.getContent(), m);
}

컨트롤러

@GetMapping("/api/users")
public PageResponse<UserDto> list(Pageable pageable) {
  Page<UserDto> page = service.find(pageable);
  return PageMappers.of(page);
}

쿼리 파라미터 예

/api/users?page=0&size=20&sort=name,asc&sort=createdAt,desc

운영 팁

• 기본 정렬을 지정해 안정적인 페이지 순서를 보장
• 대용량 테이블은 _키셋 페이징_을 고려(정확한 total 없이 커서 기반)
• 링크(다음/이전) 제공 시 HATEOAS 또는 간단한 URL 구성 포함

FAQ

Q1. 응답 크기 제한?
A. @PageableDefault(size=50)와 서버 상한을 함께 두세요.

Q2. 복합 정렬?
A. sort=fieldA,asc&sort=fieldB,desc 형태로 다중 정렬을 지원합니다.

필요하시면 각 글 하단에 넣을 이전/다음 네비게이션 박스도 Spring Boot 묶음용으로 만들어 드릴게요. 또, 특정 글에 다이어그램/표 이미지가 필요하면 말씀해 주세요. (예: 에러 응답 스키마, 캐시 흐름, 스케줄링 타임라인 등)

 

⏪ 이전 글 보기: Spring Cache로 API 3배 빠르게(@Cacheable/무효화)

 

👉 1편: Bean Validation(@Valid)로 입력 검증 표준 만들기

👉 2편: @ControllerAdvice 글로벌 예외 응답(에러코드 규격)

👉 3편: application-{profile}.yml 전략 + 비밀키 분리

👉 4편: Spring Boot Actuator: /health 커스터마이징

👉 5편: @Scheduled 크론 12패턴 + 중복실행 방지

👉 6편: 멀티파트 업로드: 제한/보안/임시저장 설계

👉 7편: Spring Cache로 API 3배 빠르게(@Cacheable/무효화)

👉 8편: Pageable 응답 DTO 규격(정렬·페이지 표준화)