페이지 번호와 커서 페이지네이션, 다음 데이터의 기준이 다른 이유
페이지 정보
본문
목록 화면의 다음 버튼은 단순해 보이지만 서버에 다음 데이터를 요청하는 기준은 여러 가지입니다. 페이지 번호 방식은 정렬된 결과에서 몇 개를 건너뛸지 계산하고, 커서 방식은 이어 읽을 위치를 나타내는 값을 전달합니다.
둘 다 결과를 나누어 가져오지만 데이터가 추가되거나 삭제될 때의 동작과 화면 이동 방식이 달라질 수 있습니다. 이 글은 특정 API를 구현하는 실습보다 두 방식의 기준과 선택 시 질문을 이해하기 위한 개념 정리입니다.
AI 생성 삽화 · 개념 이해를 위한 AI 연출 이미지이며 실제 시스템 구성도나 측정 결과가 아닙니다.
핵심 정리
페이지 번호는 결과에서의 위치를, 커서는 이어 읽을 기준을 전달합니다. 안정적인 정렬과 필터 조건이 먼저이며, 커서 사용만으로 모든 중복·누락과 동시 변경 문제가 해결되는 것은 아닙니다.
1. 페이지 번호는 건너뛸 개수로 연결할 수 있습니다
한 페이지에 20개를 보여 주는 목록에서 3페이지는 앞의 40개를 건너뛰고 다음 20개를 요청하는 방식으로 구현할 수 있습니다. 페이지 번호가 1부터 시작한다는 가정에서 건너뛸 개수는 페이지 번호에서 1을 뺀 값에 페이지 크기를 곱한 값입니다.
PostgreSQL의 LIMIT·OFFSET 문서는 반환할 행 수와 건너뛸 행 수를 구분해 설명합니다. 다만 페이지 번호가 있는 모든 API가 내부에서 정확히 이 SQL을 사용한다는 뜻은 아닙니다.
화면의 페이지 번호, API의 요청 형식, 데이터베이스의 실행 방식은 서로 다른 층입니다. 개념을 설명할 때는 어떤 층을 말하는지 먼저 정하는 편이 좋습니다.
2. 정렬이 없으면 다음의 의미가 불분명합니다
데이터베이스에 저장된 순서나 기본 키가 보인다는 이유만으로 조회 결과의 순서가 항상 고정된다고 가정하면 안 됩니다. PostgreSQL 문서는 LIMIT으로 일부를 가져올 때 예측 가능한 순서를 지정해야 한다고 안내합니다.
작성 시각만 정렬 기준으로 쓰는데 같은 시각의 행이 여러 개라면 그 안의 순서를 구분할 기준도 필요합니다. 예를 들어 작성 시각과 고유 ID를 함께 사용하는 설계를 생각할 수 있습니다.
여기서 ID는 무조건 시간 순서라는 뜻이 아니라 동률을 구분하는 값입니다. 정렬 방향과 동률 처리 기준이 요청마다 달라지면 다음 페이지라는 말도 안정적으로 정의하기 어렵습니다.
3. 커서는 이어 읽을 위치를 표현합니다
GitHub GraphQL의 페이지네이션에서는 응답의 pageInfo에서 끝 커서와 다음 페이지 존재 여부를 받고 그 커서를 after에 전달하는 흐름을 사용합니다. 이처럼 커서는 이전 응답과 다음 요청을 연결하는 값입니다.
다른 API는 다른 형식을 사용할 수 있습니다. Stripe의 해당 목록 API 문서는 객체 ID를 starting_after 등의 기준으로 사용하는 예를 보여 줍니다.
따라서 커서는 항상 숫자나 항상 특정 인코딩 문자열이라고 외울 필요가 없습니다. 클라이언트는 문서에서 보장하지 않은 내부 형식을 해석하거나 직접 만들어 내기보다 받은 값과 정해진 요청 규칙을 따라 이어 읽는 편이 안정적입니다.
4. 키셋 방식은 마지막 정렬 값을 활용합니다
커서 페이지네이션을 구현하는 한 방법은 마지막으로 본 정렬 키 이후의 행을 조건으로 조회하는 키셋 방식입니다. Microsoft의 EF Core 문서는 오프셋 방식과 키셋 방식을 비교하며 다음·이전 이동과 임의 페이지 이동의 차이를 설명합니다.
가령 고유한 정수 키를 오름차순으로 읽고 마지막 값이 80이었다면 그보다 큰 키에서 다음 묶음을 찾는 개념입니다. 작성 시각과 ID를 함께 정렬한다면 두 값의 관계를 모두 반영해야 합니다.
PostgreSQL의 행 비교 문서는 여러 값을 순서대로 비교하는 의미를 설명하지만, 실제 쿼리는 NULL 처리와 정렬 방향 등 조건을 따로 검토해야 합니다. 커서라는 외부 형식과 내부 키셋 구현을 완전히 같은 말로 취급하지 않습니다.
5. 데이터가 바뀌면 위치와 기준점의 차이가 드러납니다
직접 만든 가상 목록 A, B, C, D, E, F를 두 개씩 읽는다고 가정합니다. 처음 A와 B를 본 뒤 앞에 X가 추가되면 목록은 X, A, B, C, D, E, F가 됩니다.
다음 요청에서 단순히 두 개를 건너뛰면 B와 C가 나와 B를 다시 볼 수 있습니다. 반면 안정적인 순서에서 B 이후를 기준으로 찾는 설계라면 C부터 이어 읽도록 만들 수 있습니다.
이 예시는 특정 서비스의 실제 동작이 아니라 위치가 이동하는 상황을 설명하는 것입니다. 기준으로 사용하는 정렬 값 자체가 바뀌거나 행이 삭제되는 경우까지 같은 결과를 보장하는 것은 아니므로, 필요한 일관성은 별도 설계 문제로 봐야 합니다.
6. 다음 이동과 임의 이동의 요구를 구분합니다
계속 아래로 읽는 피드와 페이지 번호를 눌러 먼 위치로 가는 관리 화면은 사용 방식이 다릅니다. 키셋 방식은 이어 읽을 기준을 활용하므로 임의의 페이지 번호로 바로 이동하는 기능이 자연스럽게 따라오지는 않습니다.
오프셋 방식도 큰 위치까지 건너뛰는 비용을 검토해야 하며, PostgreSQL 문서는 건너뛴 행 역시 서버에서 계산되어 큰 OFFSET이 비효율적일 수 있다고 설명합니다. 어느 방식이 항상 빠르다고 단정하기보다 데이터 크기, 정렬과 인덱스, 실제 조회 계획을 확인해야 합니다.
화면 요구를 먼저 적으면 기술 이름만 보고 방식을 고르는 일을 줄일 수 있습니다.
7. 필터와 정렬이 바뀌면 읽기 흐름도 달라집니다
사용자가 전체 게시글을 읽다가 작성자 필터를 바꿨다면 앞선 위치를 그대로 이어 가는 것이 맞는지 다시 생각해야 합니다. 정렬을 최신순에서 이름순으로 바꾸는 경우도 마찬가지입니다.
직접 설계하는 API라면 커서가 어떤 검색 조건과 함께 유효한지 계약에 명시하는 편이 좋습니다. 페이지 크기 변경, 오래된 커서, 마지막 항목 삭제 같은 경우의 응답도 정해야 합니다.
이 항목들은 모든 API가 동일하게 처리한다는 설명이 아니라 구현을 검토할 때 필요한 질문입니다. 클라이언트가 임의로 조건과 커서를 섞기보다 제공자의 문서를 따라 새 조회를 시작할지 결정하도록 합니다.
8. 작은 예시로 계약과 결과를 점검합니다
연습용 목록에서 빈 결과, 한 페이지보다 적은 결과, 같은 정렬 값을 가진 행, 페이지 사이의 삽입과 삭제를 각각 생각해 볼 수 있습니다. 다음 데이터가 없는 상태를 빈 배열로 판단하는지 별도의 플래그를 사용하는지도 API 계약을 확인합니다.
GitHub의 hasNextPage와 Stripe의 has_more처럼 이름과 응답 구조는 서비스마다 다릅니다. 테스트 결과를 정리할 때는 반환된 ID 순서, 요청 조건, 다음 위치 값을 함께 기록하면 원인을 추적하기 쉽습니다.
커서가 있다는 이유만으로 최초 시점의 전체 목록을 고정해서 보는 기능이 생기지는 않습니다. 어떤 변경을 허용하고 어느 수준의 일관성이 필요한지까지 설명할 수 있어야 페이지네이션의 동작을 이해했다고 볼 수 있습니다.
9. 자주 묻는 질문
Q1. 커서 방식이면 중복과 누락이 절대 없나요?
그렇지는 않습니다. 정렬 키 변경이나 데이터 삭제, API가 제공하는 일관성 조건에 따라 결과가 달라질 수 있습니다.
안정적인 키를 사용하는 키셋 방식이 특정 위치 이동 문제를 줄일 수 있다는 설명과 모든 변경을 해결한다는 주장은 구분해야 합니다.
Q2. 페이지 번호 방식은 오래된 방식이라 쓰면 안 되나요?
임의 페이지 이동이 필요하거나 데이터 규모와 변경 특성이 맞으면 검토할 수 있습니다. 실제 성능과 화면 요구를 기준으로 판단하는 편이 좋습니다.
커서라는 이름만으로 더 적합하다고 결론 내리지 않습니다.
Q3. 커서 값을 해석해서 다음 값을 만들어도 되나요?
API가 그 형식을 공개하고 허용하지 않는다면 받은 값을 그대로 사용하는 편이 좋습니다. 내부 인코딩은 바뀔 수 있고 단순 ID가 아닐 수도 있습니다.
유효 기간과 조건 변경 규칙도 문서에서 확인합니다.
Q4. 정렬 기준에 날짜만 넣으면 충분한가요?
같은 날짜나 시각의 항목이 여러 개라면 순서가 완전히 정해지지 않을 수 있습니다. 고유 ID처럼 동률을 구분할 기준을 함께 검토합니다.
다음 조건도 선택한 정렬 기준과 일치하도록 설계해야 합니다.
참고 자료
- 이전글머신러닝 스케일링, 표준화와 정규화가 같은 말은 아닌 이유 26.09.25
- 다음글LLM 구조화 출력, JSON 형식과 내용 검증은 왜 다를까요 26.09.24
댓글목록
등록된 댓글이 없습니다.