개발자가 알아야 할 지식: 커서 페이지네이션, 다음 페이지는 숫자가 아니라 위치다

커서 페이지네이션는 코드가 커지고 사용자가 늘어날수록 조용히 중요해지는 실무 개념입니다. 처음에는 세부 구현처럼 보이지만, 실제로는 시스템이 실패를 어떻게 다룰지 정하는 기준이 됩니다.

왜 개발자가 알아야 하나

커서 페이지네이션는 작은 코드 조각보다 시스템의 약속에 더 가깝습니다.

이 기준이 없으면 구현은 동작해도 운영 순간에 비용, 장애, 데이터 불일치가 드러납니다.

개발자가 이 개념을 알면 설계 결정의 이유를 더 분명히 설명하고, 장애가 나기 전에 위험을 줄일 수 있습니다.

핵심 개념

첫 번째 핵심은 경계입니다. 커서 페이지네이션가 적용되는 범위와 적용되지 않는 범위를 구분해야 합니다. 경계가 흐리면 예외 처리가 곳곳에 흩어지고, 나중에는 같은 문제가 서로 다른 방식으로 해결됩니다.

두 번째 핵심은 계약입니다. 서버, 클라이언트, 데이터베이스, 운영 도구가 어떤 값을 믿고 어떤 실패를 허용하는지 문서와 코드에 함께 드러나야 합니다.

세 번째 핵심은 관측 가능성입니다. 제대로 설계했는지 알려면 성공 경로뿐 아니라 거절, 충돌, 지연, 재시도 같은 사건도 로그와 지표로 확인할 수 있어야 합니다.

작은 예시 또는 체크리스트

피드에서 OFFSET 1000 LIMIT 20을 쓰면 앞쪽 데이터가 추가되거나 삭제될 때 같은 항목이 다시 보이거나 건너뛸 수 있습니다. created_at과 id를 묶은 커서를 쓰면 마지막으로 본 위치 이후의 데이터를 안정적으로 가져올 수 있습니다.

• 정렬 기준이 항상 결정적이고 고유한가?
• 커서가 사용자가 임의로 조작해도 안전한 형태인가?
• 새 데이터가 끼어드는 상황에서 중복과 누락이 허용 범위 안인가?
• 역방향 페이지 이동이 필요한지 제품 요구사항을 확인했는가?
• 커서에 담긴 필드 변경이 API 호환성을 깨지 않는가?

실무에서 자주 생기는 오해

• “페이지 번호가 사용자에게 더 쉽다”는 말은 일부 화면에서만 맞습니다. 끝없는 피드나 로그에서는 위치 기반이 더 자연스럽습니다.

• “커서는 그냥 마지막 ID다”도 부족합니다. 정렬 기준이 시간이라면 동률을 깨는 ID까지 함께 필요할 수 있습니다.

• “offset도 인덱스 있으면 괜찮다”는 생각은 큰 offset에서 비용과 일관성 문제를 놓칩니다.

오늘 바로 적용해보기

무한 스크롤 API 하나를 골라 중복과 누락 가능성을 테스트하세요.

정렬 기준에 동률이 생길 때 결과 순서가 흔들리지 않는지 확인하세요.

커서 포맷을 외부 계약으로 보고 버전 변경 가능성을 고려하세요.

더 알아보기

• GraphQL Docs: Pagination
• Stripe API pagination
• PostgreSQL: LIMIT and OFFSET

오늘의 takeaway

커서 페이지네이션은 몇 번째 묶음인지보다, 마지막으로 어디까지 봤는지를 더 정확히 기억합니다.