API
REST 목록 API에 페이지네이션을 붙이며 cursor와 offset을 비교한 노트
게시글 목록이 늘어난 뒤 페이지가 밀리던 문제를 재현하고 offset과 cursor의 선택 기준을 정리했습니다.
같은 목록을 두 번 읽었는데 항목이 겹쳤다
관리자 화면에서 2페이지를 보는 사이 새 글이 발행됐다. 다음 요청을 offset=20으로 보내자 앞에서 보던 항목이 다시 나왔다. 페이지 사이에 정렬 대상이 변한 것이 원인이었다.
offset은 단순하고 cursor는 안정적이다
페이지 번호가 필요한 관리 화면에는 offset이 읽기 쉽다.
GET /api/posts?limit=20&offset=40
정렬은 반드시 고정한다.
ORDER BY published_at DESC, id DESC
무한 스크롤에는 마지막 정렬 키를 전달하는 cursor를 사용했다.
GET /api/posts?limit=20&before=2026-08-19T08:30:00Z_1842
실제 API에서는 cursor를 서명하거나 인코딩하고, 같은 시각의 행은 id로 보조한다. 그렇지 않으면 timestamp가 같은 글이 누락될 수 있다.
화면별 선택 체크
- 특정 페이지 번호로 돌아가야 하는가
- 목록 중간 삽입이 잦은가
- 전체 건수가 필요한가
- cursor를 클라이언트가 보관해도 되는가
관리자 검색에는 offset, 공개 피드에는 cursor를 남겼다. 테스트에는 같은 timestamp 두 건, 중간 삽입, 마지막 항목 삭제, limit=1을 넣었다.