spring-boot-examples/docs/pageable.md

Spring Boot의 컨트롤러에서 페이지 요청 파라미터를 받는 방법은 주로 @RequestParam 어노테이션을 사용하거나, Pageable 객체를 직접 파라미터로 받는 방식으로 구현할 수 있습니다. 두 가지 방법을 아래에서 자세히 설명하겠습니다.

---

1. @RequestParam을 사용해 개별 파라미터로 받기

이 방식은 페이지 번호(page), 페이지 크기(size), 정렬 조건(sort) 등을 개별적으로 @RequestParam으로 받아서 처리하는 방법입니다. 클라이언트가 URL 쿼리 파라미터로 값을 전달하면 이를 컨트롤러에서 수동으로 PageRequest 객체로 변환합니다.

예제 코드

import org.springframework.data.domain.Page;
import org.springframework.data.domain.PageRequest;
import org.springframework.data.domain.Sort;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class PostController {

    private final PostService postService;

    public PostController(PostService postService) {
        this.postService = postService;
    }

    @GetMapping("/posts")
    public Page<Post> getPosts(
            @RequestParam(defaultValue = "0") int page,         // 페이지 번호 (0부터 시작)
            @RequestParam(defaultValue = "10") int size,        // 페이지 크기
            @RequestParam(defaultValue = "id") String sortBy,   // 정렬 기준 필드
            @RequestParam(defaultValue = "asc") String sortDir) // 정렬 방향 (asc/desc)
    {
        // 정렬 방향 설정
        Sort.Direction direction = sortDir.equalsIgnoreCase("desc") ? Sort.Direction.DESC : Sort.Direction.ASC;
        Sort sort = Sort.by(direction, sortBy);

        // Pageable 객체 생성
        Pageable pageable = PageRequest.of(page, size, sort);

        // 서비스 호출
        return postService.getPosts(pageable);
    }
}

요청 예시

• GET /posts?page=1&size=5&sortBy=title&sortDir=desc
  • 2번째 페이지(인덱스 1), 5개 데이터, title 필드를 기준으로 내림차순 정렬
• GET /posts
  • 기본값 적용: 첫 페이지(0), 10개 데이터, id 기준 오름차순 정렬

특징

• 장점: 파라미터를 개별적으로 제어할 수 있어 유연성이 높습니다. 기본값 설정이나 추가적인 검증 로직을 쉽게 추가할 수 있습니다.
• 단점: 코드가 다소 길어질 수 있고, Pageable 객체를 직접 생성해야 합니다.

---

2. Pageable 객체를 직접 파라미터로 받기

Spring은 Pageable 타입을 컨트롤러 메서드의 파라미터로 직접 받을 수 있도록 지원합니다. Spring이 쿼리 파라미터(page, size, sort)를 자동으로 Pageable 객체로 변환해줍니다. 이 방식은 코드가 간결하고 Spring Data JPA와의 통합성이 뛰어납니다.

예제 코드

import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class PostController {

    private final PostService postService;

    public PostController(PostService postService) {
        this.postService = postService;
    }

    @GetMapping("/posts")
    public Page<Post> getPosts(Pageable pageable) {
        return postService.getPosts(pageable);
    }
}

요청 예시

• GET /posts?page=0&size=10
  • 첫 페이지(0), 10개 데이터
• GET /posts?page=1&size=5&sort=title,desc
  • 2번째 페이지(1), 5개 데이터, title 기준 내림차순 정렬
• GET /posts
  • 기본값은 애플리케이션 설정에 따라 다를 수 있음(기본적으로 page=0, size=20)

기본값 설정

Pageable의 기본값을 커스터마이징하려면 @PageableDefault 어노테이션을 사용합니다:

import org.springframework.data.domain.Pageable;
import org.springframework.data.web.PageableDefault;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class PostController {

    @GetMapping("/posts")
    public Page<Post> getPosts(
            @PageableDefault(page = 0, size = 10, sort = "id", direction = Sort.Direction.ASC) Pageable pageable) {
        return postService.getPosts(pageable);
    }
}

요청 예시 (기본값 적용)

• GET /posts
  • 첫 페이지(0), 10개 데이터, id 기준 오름차순 정렬

sort 파라미터 형식

• sort=fieldName,direction 형식으로 전달합니다.
  • 예: sort=title,desc (title 기준 내림차순)
  • 여러 필드 정렬: sort=title,desc&sort=id,asc

---

두 방식의 비교

방식	장점	단점
@RequestParam	세밀한 제어 가능, 기본값 명시적 설정 가능	코드가 길어질 수 있음
Pageable 직접 사용	간결한 코드, Spring과의 높은 통합성	기본값 설정이 별도로 필요할 수 있음

---

추가 팁

1. 전역 기본값 설정
   application.properties나 application.yml에서 Pageable의 기본값을 설정할 수 있습니다:

   spring.data.web.pageable.default-page-size=10
   spring.data.web.pageable.max-page-size=100
   

2. 검증 추가
   페이지 번호나 크기가 음수로 들어오지 않도록 컨트롤러에서 검증 로직을 추가할 수 있습니다:

   if (page < 0 || size <= 0) {
       throw new IllegalArgumentException("페이지 번호는 0 이상, 크기는 1 이상이어야 합니다.");
   }
   

3. 응답 커스터마이징
   Page<Post>를 그대로 반환하면 JSON에 모든 메타데이터가 포함됩니다. 필요한 정보만 반환하려면 DTO로 변환해 응답을 구성할 수 있습니다:

   public class PostResponse {
       private List<Post> content;
       private int totalPages;
       private long totalElements;
   
       public PostResponse(Page<Post> page) {
           this.content = page.getContent();
           this.totalPages = page.getTotalPages();
           this.totalElements = page.getTotalElements();
       }
   }
   

---

결론

컨트롤러에서 페이지 요청 파라미터를 받는 방법은 @RequestParam으로 개별 파라미터를 처리하거나, Pageable을 직접 사용하는 두 가지가 주로 사용됩니다. 간단한 경우에는 Pageable을 직접 사용하는 방식이 편리하고, 세밀한 제어가 필요할 때는 @RequestParam을 활용하는 것이 좋습니다. 프로젝트의 요구사항에 맞게 선택하면 됩니다!