API 分頁設計：Offset vs Cursor-based Pagination 如何選擇？

API 分頁設計

Offset-based Pagination

GET /api/posts?offset=20&limit=10

✅ 簡單直覺，支援跳頁 ❌ 大資料量效能差（OFFSET N 需掃描前 N 筆） ❌ 資料新增/刪除時產生漏資料或重複資料

Cursor-based Pagination（推薦）

GET /api/posts?cursor=eyJpZCI6MTAwfQ&limit=10

Cursor 通常是上一頁最後一筆的 ID 或時間戳（Base64 編碼）

✅ 效能穩定，不受資料量影響 ✅ 即時資料不會漏資料或重複 ❌ 無法跳頁（只能上一頁/下一頁）

Keyset Pagination（Cursor 的變形）

GET /api/posts?after_id=100&limit=10

利用索引欄位（ID、created_at）直接過濾，SQL 查詢效率高

選擇指南

需求	建議
後台管理列表、支援跳頁	Offset
Feed、Timeline、無限滾動	Cursor / Keyset
大資料量 API	Cursor / Keyset

回應格式（以 Cursor 為例）

{ data: [...], next_cursor: "...", has_more: true }