원인 모를 버그 없이 안정적인 API 목록을 위한 커서 페이지네이션

문제: 발 밑에서 바뀌는 목록\n\n피드를 열고 조금 스크롤하는데 모든 게 정상이다가 갑자기 이상해집니다. 같은 항목이 두 번 보이거나, 분명히 있던 항목이 사라지거나, 탭하려던 행이 아래로 밀려 잘못된 상세 페이지로 들어갑니다.\n\n이런 현상은 사용자가 직접 볼 수 있는 버그입니다. API 응답 자체는 각각 보면 “정상”처럼 보여도, 연속된 페이지 요청에서는 문제가 드러납니다. 일반적인 증상은 다음과 같습니다:\n\n- 페이지 간 중복 항목\n- 한 번도 보지 못한 항목의 누락\n- 스크롤 도중 항목 위치가 튀는 현상\n- 무한 스크롤이 일찍 멈추거나 같은 페이지를 다시 불러오는 현상\n\n특히 모바일에서 더 심합니다. 사용자는 잠시 멈추고, 앱을 전환하고, 네트워크가 끊겼다 이어지는 일이 많습니다. 그 사이에 새 항목이 들어오고, 기존 항목이 삭제되거나 수정됩니다. 앱이 계속 page 3 같은 오프셋을 요청하면, 사용자가 스크롤하는 도중에 페이지 경계가 이동합니다. 결과는 불안정하고 신뢰할 수 없는 피드입니다.\n\n목표는 단순합니다: 사용자가 앞으로 스크롤하기 시작하면 목록은 스냅샷처럼 행동해야 합니다. 새 항목은 존재할 수 있지만 이미 페이징한 항목의 순서를 뒤섞어서는 안 됩니다. 사용자는 부드럽고 예측 가능한 순서를 받아야 합니다.\n\n완벽한 페이지네이션 방법은 없습니다. 실제 시스템에는 동시 쓰기, 수정, 여러 정렬 옵션이 존재합니다. 하지만 커서 페이지네이션은, 오프셋이 이동하는 행 수에 의존하는 대신 정렬된 위치에서 이어가기 때문에 보통 더 안전합니다.\n\n## 오프셋 페이지네이션 1분 요약\n\n오프셋 페이징은 "건너뛰기 N, 가져오기 M" 방식입니다. API에 몇 건을 건너뛸지(offset)와 몇 건을 반환할지(limit)를 알려줍니다. 예를 들어 limit=20이면 한 페이지당 20건을 받습니다.\n\n개념적으로:\n\n- GET /items?limit=20\u0026offset=0 (첫 페이지)\n- GET /items?limit=20\u0026offset=20 (두 번째 페이지)\n- GET /items?limit=20\u0026offset=40 (세 번째 페이지)\n\n응답에는 보통 항목들과 다음 페이지를 요청하는 데 필요한 정보가 포함됩니다.\n\n```json\n{

"items": [ {"id": 101, "title": "..."}, {"id": 100, "title": "..."} ], "limit": 20, "offset": 20, "total": 523 } json GET /api/messages?limit=30&cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wMS0xNlQxMDowMDowMFoiLCJpZCI6Ijk4NzYifQ== json { "items": [ {"id":"9876","created_at":"2026-01-16T10:00:00Z","subject":"..."} ], "next_cursor": "...", "has_more": true } ```\n\n서버 측 논리는 간단합니다: 안정적인 순서로 정렬하고, 커서를 사용해 필터링한 뒤 을 적용하세요.\n\n예를 들어 로 최신순 정렬한다면, 커서를 로 디코드해서 쌍이 커서보다 엄격히 작은 행들을 같은 정렬로 가져오고 만큼 취하세요.\n\n### 3) 커서 인코딩: 불투명(opaque)이 낫다\n\n커서는 base64로 인코딩된 JSON 블롭처럼 간단하게 만들거나, 서명/암호화된 토큰처럼 더 안전하게 만들 수 있습니다. 불투명 토큰이 더 안전한 이유는 내부 구조를 나중에 바꿀 수 있기 때문입니다.\n\n또한 기본값을 합리적으로 설정하세요: 모바일 기본값(보통 20~30), 웹 기본값(보통 50), 그리고 버그난 클라이언트가 수천 건을 요청하지 못하도록 서버에서 하드맥스를 두세요.\n\n## 삽입, 삭제, 편집 항목 처리\n\n안정적인 피드는 한 가지 약속에 관한 것입니다: 사용자가 앞으로 스크롤하기 시작하면, 다른 사람이 레코드를 생성·삭제·수정했다고 해서 사용자가 보려던 항목들이 튀지 않아야 합니다.\n\n커서 페이지네이션에서는 삽입이 가장 쉽습니다. 새 레코드는 새로고침에서 보이게 하고, 이미 로드한 페이지 중간에 섞이지 않게 하세요. 로 정렬하면 새 항목은 자연스럽게 첫 페이지 앞에 놓이고 기존 커서는 더 오래된 항목으로 계속 이어집니다.\n\n삭제는 목록을 뒤섞지 않아야 합니다. 항목이 삭제되면 단지 그 항목이 반환되지 않을 뿐입니다. 페이지 크기를 일정하게 유지해야 한다면, 실제로 보이는 개의 항목을 모을 때까지 계속 가져오면 됩니다.\n\n편집은 팀이 실수로 버그를 다시 도입하는 지점입니다. 핵심 질문은: 편집으로 정렬 위치가 바뀔 수 있는가? 입니다.\n\n### 스냅샷 방식과 라이브 방식 중 선택\n\n스냅샷 스타일은 스크롤 목록에 보통 더 적합합니다: 같은 불변 키로 페이지를 나누세요. 내용은 편집될 수 있지만 항목이 새 위치로 점프해서는 안 됩니다.\n\n라이브 피드는 같은 필드로 정렬하면 오래된 항목이 편집되며 위쪽으로 이동하는 등 점프가 발생할 수 있습니다. 이 방식을 선택하면 목록이 계속 변한다고 간주하고 UX를 새로고침 위주로 설계하세요.\n\n### 커서 항목이 더 이상 존재하지 않을 때\n\n커서를 "이 정확한 행을 찾아라"에 의존하지 마세요. 대신 마지막으로 반환한 항목의 처럼 위치 값을 인코딩하세요. 그러면 다음 쿼리는 행 존재 여부에 의존하지 않고 값 기반으로 동작합니다:\n\n- 내림차순인 경우: \n- 항상 같은 타이브레이커를 포함해 중복을 피하세요\n- 마지막 항목이 삭제되어도 값은 여전히 작동합니다\n- 마지막 항목이 편집되었더라도 정렬 키가 불변이라면 여전히 작동합니다\n\n## 뒤로 페이징, 새로고침, 임의 접근\n\n앞으로 페이징은 쉬운 편입니다. 더 까다로운 UX 문제는 뒤로 페이징, 새로고침, 임의 접근입니다.\n\n뒤로 페이징에는 보통 두 가지 접근이 효과적입니다:\n\n- 양방향을 반환하기: (오래된 항목)와 (더 새로운 항목)를 모두 반환하면서 화면 내 정렬은 하나로 유지하기\n- 단일 커서를 유지하되 사용자가 위로 스크롤할 때는 정렬을 반대로 요청하기\n\n커서로는 ‘20페이지’ 같은 랜덤 점프가 안정적 의미를 갖기 어렵습니다. 진짜 점프가 필요하면 ‘이 타임스탬프 주변’ 또는 ‘이 메시지 id부터 시작’ 같은 앵커로 이동한 뒤 그 지점에서 커서로 페이징하세요.\n\n모바일에서는 캐싱이 중요합니다. 쿼리+필터+정렬별로 커서를 저장하고 각 탭/뷰를 별개의 목록으로 취급하세요. 그래야 탭을 전환할 때 목록이 뒤죽박죽 되는 것을 막을 수 있습니다.\n\n## "원인 모를" 버그를 만드는 일반적인 실수\n\n대부분의 커서 페이지네이션 문제는 데이터베이스 때문이 아니라 요청 간의 작은 불일치에서 옵니다. 실사용 트래픽에서만 드러나는 경우가 많습니다.\n\n가장 큰 범인은:\n\n- 고유하지 않은 커서 사용(예: 만 사용)으로 인해 타이에서 중복 또는 누락 발생\n- 실제로 반환한 마지막 항목과 일치하지 않는 반환\n- 페이지 요청 사이에 필터나 정렬을 변경함\n- 동일한 엔드포인트에서 오프셋과 커서를 혼용함\n\nKoder.ai 같은 플랫폼 위에 앱을 올리면 웹과 모바일 클라이언트가 같은 엔드포인트를 공유하는 경우가 많아 이런 엣지케이스가 빨리 드러납니다. 하나의 명확한 커서 계약과 결정론적 정렬 규칙을 갖추면 두 클라이언트가 일관되게 동작합니다.\n\n## 배포 전에 확인할 빠른 체크리스트\n\n페이지네이션을 "완료"라고 부르기 전에 삽입, 삭제, 재시도 상황에서 동작을 확인하세요.\n\n- 정렬이 명시적이며 결정론적이고 타이브레이커를 포함하는가\n- 모든 요청이 동일한 필터와 정렬 필드를 반복하는가\n- 를 실제로 반환한 마지막 행에서 가져오는가\n- 에 안전한 최대값과 문서화된 기본값이 있는가\n- 새 항목 처리(새로고침 동작)가 정의되어 있는가\n\n새로고침에 대해서는 하나의 명확한 규칙을 정하세요: 사용자가 당겨서 새로고침하면 맨 위의 최신 항목을 가져오거나, 아니면 주기적으로 "내 첫 항목보다 최신 항목이 있는가?"를 확인해 "새 항목" 버튼을 보여주는 방식 중 하나를 선택하세요. 일관성이 있어야 목록이 불안정하게 보이지 않습니다.\n\n## 현실적인 예: 장치 간에 안정적으로 유지되는 인박스\n\n웹에서 에이전트가 사용하는 지원 인박스와 모바일에서 매니저가 확인하는 같은 인박스를 생각해보세요. 목록은 최신순이고 사람들은 하나의 기대를 가집니다: 앞으로 스크롤할 때 항목이 점프하거나 반복되거나 사라지지 말아야 한다는 것.\n\n오프셋 페이징에서는 에이전트가 1페이지(1–20)를 로드하고 으로 2페이지를 보려 할 때, 그 사이에 상단에 두 통의 새 메시지가 도착하면 은 이전과 다른 위치를 가리키게 됩니다. 사용자는 중복을 보거나 메시지를 놓칩니다.\n\n커서 페이지네이션에서는 앱이 "이 커서 뒤의 다음 20개"를 요청합니다. 커서는 사용자가 실제로 마지막으로 본 항목(보통 )을 기반으로 합니다. 새 메시지는 계속 들어오더라도 다음 페이지는 여전히 사용자가 본 마지막 메시지 바로 다음부터 시작합니다.\n\n출시 전 간단한 테스트 방법:\n\n- 페이지를 가져오는 동안 스크립트로 초당 새 메시지를 삽입하세요\n- 스크롤 중간에 몇 개의 메시지를 삭제하세요\n- 메시지를 편집하되 정렬 필드는 변경하지 마세요\n- 중복, 빈칸, 또는 순서가 뒤틀리는 일이 없는지 확인하세요\n- 모바일 앱과 웹 앱이 일관된 페이지 경계를 보여주는지 검증하세요\n\n빠르게 프로토타입을 만들고 있다면 Koder.ai는 챗 프롬프트에서 엔드포인트와 클라이언트 플로를 스캐폴딩하고, Planning Mode와 스냅샷/롤백으로 안전하게 반복할 수 있게 도와줍니다.