spring-boot-examples/docs/pageable.md

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

---

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

#### 예제 코드
```java
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와의 통합성이 뛰어납니다.

#### 예제 코드
```java
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` 어노테이션을 사용합니다:
```java
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`의 기본값을 설정할 수 있습니다:
   ```properties
   spring.data.web.pageable.default-page-size=10
   spring.data.web.pageable.max-page-size=100
   ```

2. **검증 추가**  
   페이지 번호나 크기가 음수로 들어오지 않도록 컨트롤러에서 검증 로직을 추가할 수 있습니다:
   ```java
   if (page < 0 || size <= 0) {
       throw new IllegalArgumentException("페이지 번호는 0 이상, 크기는 1 이상이어야 합니다.");
   }
   ```

3. **응답 커스터마이징**  
   `Page<Post>`를 그대로 반환하면 JSON에 모든 메타데이터가 포함됩니다. 필요한 정보만 반환하려면 DTO로 변환해 응답을 구성할 수 있습니다:
   ```java
   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`을 활용하는 것이 좋습니다. 프로젝트의 요구사항에 맞게 선택하면 됩니다!