처음 API를 설계할 때 Pagination을 단순히 '데이터를 여러 페이지로 나누는 것' 정도로만 생각했습니다. 그런데 실제 운영 환경에서 데이터가 쌓이고 사용자가 늘어나면서, 이게 단순한 기능이 아니라 서비스 성능과 사용자 경험을 좌우하는 핵심 설계 문제라는 걸 뼈저리게 느꼈습니다. 특히 대량의 로그 데이터를 다루는 프로젝트에서 Pagination 방식 하나 때문에 응답 속도가 10배 이상 차이 나는 걸 직접 확인하면서, 이 문제를 제대로 이해해야겠다고 다짐했습니다.
성능 최적화 효과
API Pagination(페이지네이션)은 대량의 데이터를 한 번에 전달하지 않고 여러 페이지로 나누어 제공하는 설계 전략입니다. 쉽게 말해 수천 개의 데이터를 한 번에 던지지 않고, 10개씩 또는 20개씩 끊어서 보내는 방식이라고 생각하면 됩니다. 제가 담당했던 프로젝트에서 초기에는 이 개념을 제대로 적용하지 않았는데, 사용자가 늘어나면서 서버 메모리가 급격히 증가하고 응답이 느려지는 문제가 발생했습니다.
Pagination을 도입하고 나서 가장 먼저 체감한 건 서버 부하 감소였습니다. 한 번의 요청에서 처리하는 데이터 양이 제한되니까, 서버 메모리 사용량이 안정적으로 유지되고 네트워크 전송 부담도 크게 줄었습니다. 특히 모바일 환경에서는 데이터 전송량이 줄어들면서 사용자 체감 속도가 눈에 띄게 개선되었습니다. 실제로 한 페이지당 20개로 제한했을 때, 이전 대비 응답 시간이 평균 70% 정도 단축되는 걸 확인할 수 있었습니다.
데이터 탐색 제약 문제
하지만 Pagination에는 명확한 단점도 있습니다. 데이터를 여러 페이지로 나누면서 전체 데이터를 한눈에 보거나 분석하려는 사용자에게는 오히려 불편함을 초래합니다. 제가 운영했던 서비스에서 데이터 분석팀이 가장 먼저 불만을 제기한 부분이 바로 이것이었습니다. 그들은 전체 데이터를 한 번에 내려받아 엑셀로 분석하고 싶어 했는데, Pagination 때문에 여러 번 API를 호출해야 했습니다.
실무에서는 이런 요구사항을 해결하기 위해 별도의 데이터 추출 API를 제공하거나, Pagination 크기를 조정할 수 있는 파라미터를 추가하는 방식으로 대응했습니다. 다만 이 경우에도 무제한으로 데이터를 내려줄 수는 없었고, 최대 페이지 크기를 500개 정도로 제한하면서 성능과 사용성 사이에서 균형점을 찾았습니다. 결국 Pagination은 성능을 위해 일부 사용 편의성을 포기하는 트레이드오프(trade-off) 관계에 있다는 걸 경험으로 확인했습니다.
Cursor 기반 방식으로의 전환
Pagination에는 크게 두 가지 구현 방식이 있습니다. Offset 기반과 Cursor 기반입니다. Offset 기반 Pagination은 페이지 번호와 크기를 지정하는 방식으로, 구현이 단순하고 직관적입니다. 예를 들어 "page=2&size=20" 같은 형태로 요청하면, 21번째부터 40번째 데이터를 반환합니다. 처음에는 이 방식을 사용했는데, 데이터가 수십만 건을 넘어가면서 문제가 생겼습니다.
특정 페이지를 조회할 때마다 데이터베이스가 처음부터 해당 위치까지 모든 데이터를 건너뛰어야 하기 때문에, 뒤쪽 페이지로 갈수록 조회 속도가 급격히 느려졌습니다. 실제로 1,000페이지 이후부터는 응답 시간이 5초 이상 걸리는 경우도 있었습니다. 이 문제를 해결하기 위해 Cursor 기반 Pagination으로 구조를 변경했습니다(출처: PostgreSQL 공식 문서).
Cursor 기반 방식은 마지막으로 조회한 데이터의 고유 식별자(예: ID 값)를 기준으로 다음 데이터를 가져오는 방식입니다. 이 방식을 적용한 후 대량 데이터 환경에서도 일관된 조회 성능을 유지할 수 있었습니다. 다만 구현 복잡성이 증가했고, 클라이언트 개발자들이 이 개념을 이해하는 데 시간이 필요했습니다. 그래서 API 문서에 Cursor 사용 예시를 상세히 작성하고, 샘플 코드를 함께 제공하는 방식으로 학습 비용을 줄이려고 노력했습니다.
두 방식의 차이를 정리하면 다음과 같습니다:
- Offset 기반: 구현이 간단하고 특정 페이지로 바로 이동 가능하지만, 대량 데이터에서 성능 저하 발생
- Cursor 기반: 안정적인 성능 유지 가능하지만, 구현 복잡도가 높고 특정 페이지로 직접 이동 불가
- 선택 기준: 데이터 규모와 사용 패턴에 따라 결정해야 하며, 두 방식을 병행 제공하는 것도 고려할 수 있음
설계 단계에서의 고려사항
Pagination 전략은 프로젝트 초기부터 신중하게 설계해야 합니다. 나중에 방식을 변경하려면 클라이언트 코드 수정이 불가피하고, 하위 호환성 문제도 발생하기 때문입니다. 새 프로젝트를 시작할 때 다음과 같은 기준으로 접근합니다. 데이터가 10만 건 이하로 예상되면 Offset 기반으로 시작하되, 그 이상 규모라면 처음부터 Cursor 기반을 적용합니다.
또한 Pagination 크기도 중요한 설계 요소입니다. 너무 작으면 API 호출 횟수가 증가하고, 너무 크면 한 번의 응답이 느려집니다. 제가 운영한 서비스에서는 기본값을 20개로 설정하고, 사용자가 10~100개 범위에서 조정할 수 있도록 했습니다. 모바일 환경에서는 10개, 데스크톱 환경에서는 50개 정도가 적당하다는 걸 사용 패턴 분석을 통해 확인했습니다.
마지막으로 전체 데이터 개수(total count)를 함께 반환할지도 고민해야 합니다. 사용자 경험상으로는 전체 페이지 수를 알려주는 게 좋지만, 이 값을 계산하는 데 추가 쿼리가 필요하고 성능 부담이 생길 수 있습니다. 데이터가 자주 변경되지 않는 경우에만 total count를 제공하고, 실시간 데이터의 경우 'hasNext' 같은 불리언 값만 반환하는 방식으로 대응했습니다.
Pagination은 단순한 기술 선택이 아니라, 서비스의 데이터 특성과 사용자 요구사항을 모두 고려해야 하는 설계 문제입니다. 성능만 생각하면 모든 데이터를 잘게 쪼개면 되지만, 그러면 사용자가 불편해집니다. 반대로 사용자 편의만 생각하면 서버가 버티지 못합니다. 이 두 가지 사이에서 균형점을 찾는 과정이 백엔드 개발자로서 가장 중요한 역량 중 하나라고 생각합니다. 앞으로 API를 설계할 때는 Pagination 전략을 초기부터 명확히 정의하고, 데이터 증가에 대비한 확장 계획도 함께 수립하시길 권장합니다.
댓글
댓글 쓰기