목록 API에서 페이지 번호 대신 커서를 쓰는 이유

목록 API가 페이지 번호와 크기를 받으면 사용하기 쉽습니다. 하지만 목록이 조회 도중 계속 바뀌는 주문·이벤트 데이터에서는 1페이지와 2페이지 사이에 새 항목이 들어와 같은 항목을 두 번 보거나 하나를 놓칠 수 있습니다.

오프셋의 이동을 이해한다

최신순 목록에서 첫 페이지를 읽은 뒤 새 주문이 추가되면 뒤의 행 위치가 한 칸씩 밀립니다. 다음 페이지를 오프셋으로 읽으면 앞에서 봤던 주문이 다시 나올 수 있습니다. 특히 최신순 목록을 계속 스크롤하는 화면과 전체 데이터를 한 번만 동기화하는 작업은 요구가 다릅니다. 전자는 사용자 경험을, 후자는 누락 없이 끝까지 읽는 것을 우선해 커서 정책을 설계합니다.

정렬 기준을 고정한다

커서는 마지막으로 본 항목의 생성 시각과 고유 ID 같은 안정적인 정렬 키를 담습니다. 시각만으로 정렬하면 같은 밀리초에 생성된 항목 순서를 결정하기 어려우므로 보조 키가 필요합니다.

필터와 커서를 묶는다

고객·상태 필터를 바꾸면서 이전 커서를 재사용하면 누락이나 예상 밖 결과가 나옵니다. 커서가 어떤 쿼리 조건과 정렬에 속하는지 확인하고 형식은 외부에 불투명하게 제공합니다.

삭제와 갱신의 의미를 정한다

커서도 모든 변경 상황에서 동일한 스냅샷을 보장하지는 않습니다. 삭제되거나 정렬 키가 바뀐 항목을 어떻게 처리할지 정하고, 정확한 시점 고정이 필요하면 별도 스냅샷 전략을 사용합니다.

클라이언트 계약을 단순하게 한다

응답에 다음 커서와 더 읽을 항목이 있는지를 제공하고, 만료된 커서는 명확히 알려줍니다. 대량 동기화에는 중복 가능성을 감안해 클라이언트도 항목 ID로 멱등 처리해야 합니다.

현장에 적용할 때의 순서

1. 안정적인 정렬 키와 다음 커서 정의
2. 커서에 필터·정렬 조건 일치 여부 적용
3. 동시 삽입·삭제 시 중복·누락 시험

주의할 실패: 커서가 자동으로 고정 스냅샷을 보장한다고 가정

관찰할 지표: 중복·누락 건수·페이지 조회 지연

적용 전 체크리스트

• 정렬 키에 고유한 보조 ID를 포함한다
• 필터가 바뀌면 이전 커서를 거절한다
• 중복·누락을 동시 삽입 테스트로 확인한다

참고 자료

Stripe API — Pagination. 커서 기반 페이지네이션의 실제 API 형태는 Stripe 공식 문서를 참고했습니다. 정렬 키와 동시 변경 테스트는 일반 설계 제안입니다.

이미지와 도식은 이해를 돕기 위한 개념 시각화입니다. 특정 고객의 실제 설비·데이터·화면을 재현한 것이 아닙니다.

#API설계 #커서페이지네이션 #Pagination #목록API #데이터동기화 #정렬 #오프셋 #분산시스템 #웹개발 #멱등성