📄 Pageable로 페이징 처리 쉽게 구현하기 (+Spring Data JPA)

1. 페이징 처리가 필요한 이유

블로그나 커뮤니티 게시판처럼 많은 데이터를 다루는 서비스에서 모든 데이터를 한 번에 내려주는 것은 비효율적이다. 서버에는 불필요한 부하가 발생하고 클라이언트 역시 네트워크 낭비와 렌더링 지연을 겪을 수 있다.

이러한 문제를 해결하기 위해 일반적으로 페이징 처리(Pagination)를 사용한다. 데이터를 일정 단위로 나누어 전달하면 클라이언트는 필요한 페이지만 요청해 효율적으로 화면에 데이터를 표시할 수 있다.

Spring Boot에서는 Pageable을 활용해 비교적 간단하게 페이징 처리를 구현할 수 있다.

2. Pageable 인터페이스와 사용 방법

Pageable은 Spring Data에서 제공하는 페이징 정보를 담는 인터페이스로 페이지 번호, 페이지 크기, 정렬 정보 등을 포함한다.

Spring Boot에서는 Pageable 객체를 컨트롤러 파라미터로 선언하면 클라이언트의 페이징 요청을 자동으로 바인딩해준다.

[클라이언트 요청 예시]
GET /posts?page=0&size=10&sort=createdAt,desc​

@GetMapping
public PageResponse<PostListResponse> getAllPosts(
    @PageableDefault(
        page = 0, 
        size = 10, 
        sort= { "createdAt", "id" }, 
        direction = Sort.Direction.DESC
    ) Pageable pageable
) {    
  Page<PostListResponse> page = userPostService.getAllPosts(pageable)
      .map(PostListResponse::from);
      
  return PageResponse.from(page);
}

Pageable은 기본적으로 page, size, sort라는 요청 파라미터 이름을 기준으로 바인딩된다. 클라이언트에서 다른 이름으로 전달하면 인식되지 않으며 필요하다면 spring.data.web.pageable 설정을 통해 파라미터 이름을 변경할 수 있다.

sort 파라미터는 여러 개 전달할 수 있으며 전달된 순서대로 정렬 조건이 적용된다.

[createdAt DESC -> title ASC 순서로 적용]
GET /posts?sort=createdAt,desc&sort=title,asc

@PageableDefault는 Pageable의 기본값을 설정할 때 사용한다. 설정 가능한 주요 파라미터는 다음과 같다.

• page: 기본 페이지 번호 (주로 0-based)
• size: 한 페이지에 조회할 데이터 개수
• sort: 정렬 기준 필드
• direction: 정렬 방향 (ASC / DESC)

이후 컨트롤러에서 전달받은 Pageable 객체를 그대로 서비스 계층으로 전달하여 페이징 조회 로직을 구현하였다.

public Page<PostListDto> getAllPosts(Pageable pageable) {
    Page<Post> page = postRepository.findVisiblePosts(pageable);
    return page.map(PostListDto::of);
}

3. Spring Data JPA 페이징 처리 방식

@EntityGraph(attributePaths = { "category", "medias" })
@Query("SELECT p FROM Post p WHERE p.status = 'PUBLISHED'")
Page<Post> findAllPublished(Pageable pageable);

findAllPublished()는 레포지토리에서 @Query를 사용하여 직접 작성한 커스텀 JPA 쿼리 메서드이며 @EntityGraph를 통해 연관 엔티티를 함께 조회하도록 설정하였다. (참고)

레포지토리 메서드에 Pageable이 포함되면 Spring Data JPA는 다음과 같이 동작한다.

1. 기본 조회 쿼리를 생성한다.
2. 전체 데이터 개수를 계산하기 위한 count query를 실행한다.
3. Pageable 정보(page, size, sort)를 기반으로 SQL에 LIMIT과 OFFSET을 적용한다.
 
[실제 SQL 변환 예시]

select
  p1_0.id,
  p1_0.title,
  p1_0.slug,
  p1_0.content,
  -- 이하 생략
from
  post p1_0
left join
  category c1_0
    on c1_0.id=p1_0.category_id
left join
  media m1_0
    on p1_0.id=m1_0.post_id​
where
  p1_0.status='PUBLISHED'
order by
  p1_0.created_at desc,
  p1_0.id desc
fetch
  first ? rows only

fetch first ? rows only 구문은 PostgreSQL에서 사용하는 페이징 문법으로 MySQL의 limit ? 과 동일한 역할을 한다. 즉 앞에서부터 지정된 개수만큼의 행을 조회한다는 의미이다.

또한 첫 페이지를 요청하는 경우 OFFSET 값은 생략될 수 있다.

Spring Data JPA는 Pageable 객체를 기반으로 페이징 SQL을 자동 생성하기 때문에 SQL을 직접 작성하지 않고도 효율적인 페이징 처리를 구현할 수 있다.

반환 타입: Page, Slice, List

Spring Data JPA에서는 페이징 조회 시 반환 타입을 선택할 수 있다.

Page
전체 데이터 개수와 페이지 정보를 포함하는 객체이다. 총 페이지 수, 현재 페이지 번호, 페이지 크기를 확인할 수 있다.

일반적인 게시판 조회에 적합하지만 데이터 전체 개수를 계산하기 위한 count query가 추가로 실행될 수 있다.

Slice
Slice는 다음 페이지 존재 여부만 확인하는 반환 타입이다. count query를 실행하지 않기 때문에 성능 측면에서 Page보다 유리할 수 있다.

전체 페이지 수가 필요하지 않은 무한 스크롤 UI에 적합하다.

List
List는 페이징 정보를 포함하지 않고 데이터 목록만 반환한다. 단순 조회 또는 별도의 페이징 정보가 필요하지 않은 경우 사용한다.

4. 실무 적용 시 고려사항

응답 DTO

컨트롤러에서 반환 시 Page<T>를 그대로 사용하지 않고 응답 DTO를 별도로 정의하는 것이 일반적이다.

Page 객체에는 페이징 관련 메타 정보뿐만 아니라 다양한 내부 정보가 포함되어 있다. 따라서 불필요한 내부 정보 노출을 방지하고 클라이언트에게 필요한 데이터만 전달하기 위해 응답 DTO를 분리하여 사용하는 것이 좋다.

또한 API 응답 구조를 명확하게 관리할 수 있어 유지보수 측면에서도 유리하다.

Cursor 기반 Pagination (Keyset Pagination)

Pageable은 기본적으로 Offset 기반으로 동작한다. Offset 기반 Pagination은 페이지 번호와 offset을 이용하여 데이터를 조회하는 방식이다. 하지만 페이지 번호가 커질수록 이전 데이터를 모두 건너뛰어야 하므로 데이터가 많아질수록 성능이 저하될 수 있다.

반면 Cursor 기반 Pagination은 마지막으로 조회한 데이터의 위치를 기준으로 다음 데이터를 조회하는 방식이다. 대표적으로 다음과 같은 값을 Cursor로 사용할 수 있다.

• 마지막으로 조회한 ID
• 생성 시간 (timestamp)

Cursor Pagination은 Offset 방식보다 성능이 안정적이며 대량 데이터 조회나 무한 스크롤 UI에 적합하다.

다만 구현이 상대적으로 복잡하고 정렬 기준이 제한될 수 있으며 자유로운 페이지 이동이 어렵다는 단점이 있다. 따라서 사용 목적에 따라 Pagination 방식을 선택하는 것이 중요하다.