API Sayfalama: Offset ve Cursor Yöntemleri Arasındaki Fark
Büyüyen ürün veya sipariş listelerinde tüm kayıtları tek yanıtta göndermek yerine offset ve cursor tabanlı sayfalamayı nasıl seçebileceğinizi, tutarlılık ve sıralama örnekleriyle inceleyin.
İlk geliştirme gününde /api/products uç noktasının birkaç kaydı tek yanıtta döndürmesi yeterli görünebilir. Liste büyüdüğünde yanıt boyutu, veritabanı maliyeti ve istemci belleği sorun olmaya başlar. Sayfalama bu yükü sınırlar; ancak hangi yöntemin seçildiği, hareketli veride kayıtların kaçırılıp kaçırılmayacağını da etkiler.
Offset yaklaşımı nasıl çalışır?
Offset tabanlı bir API genellikle ?page=3&per_page=20 veya ?offset=40&limit=20 kabul eder. Mantık basittir: ilk 40 kaydı atla, sonraki 20 kaydı getir. Yönetim panelinde doğrudan beşinci sayfaya gitmek isteyen kullanıcılar için anlaşılırdır. Toplam kayıt sayısını da döndürüyorsanız kullanıcı kaç sayfa olduğunu görebilir; ancak toplamı hesaplamanın büyük sorgularda ayrıca maliyeti olabilir.
Sorguda kararlı sıralama şarttır. Yalnızca created_at kullanılır ve birçok kayıt aynı anda oluşursa bağların sırası değişebilir. İkinci bir benzersiz sıralama anahtarı eklemek daha güvenlidir: ORDER BY created_at DESC, id DESC. İlgili veritabanı indekslerini ve sorgu planını gerçek veride kontrol edin.
Offset'in iki önemli sınırı vardır. Büyük offset değerlerinde veritabanı birçok satırı atlamak zorunda kalabilir. Ayrıca kullanıcı ilk sayfayı gördükten sonra listenin başına yeni kayıt eklenirse ikinci sayfada bazı kayıtlar tekrarlanabilir veya atlanabilir. Bu davranış sorguya ve değişikliklere bağlıdır; sadece indeks eklemek hareket eden listenin mantığını düzeltmez.
Cursor yaklaşımı neyi değiştirir?
Cursor, sayfa numarasından çok “son gördüğüm konumdan devam et” fikrini kullanır. Örneğin ilk yanıtta son ürünün sıralama değerleriyle temsil edilen bir devam işareti döndürülür; sonraki istekte istemci bu işareti sunucuya verir. Sunucu sıralamadaki o konumdan sonra gelenleri arar.
Aşağıdaki sadeleştirilmiş SQL, artan sayısal kimlikle ilerlemeyi gösterir. Gerçek uygulamada erişim filtresi ve ürünün görünürlüğü gibi koşullar da eklenmelidir:
SELECT id, name
FROM products
WHERE id > :last_id
ORDER BY id ASC
LIMIT :page_size;
Kimlikler benzersiz ve sıralama değişmiyorsa istemci aldığı son kimlikle devam edebilir. created_at gibi tek başına benzersiz olmayan bir sıralamada cursor iki alanı da taşımalıdır; karşılaştırma koşulu ve sıralama aynı mantıkla kurulmalıdır. Cursor'u dışarıya opak bir değer olarak sunmak uygulama ayrıntılarını değiştirmeyi kolaylaştırır; ancak Base64 kodlamak tek başına gizlilik veya bütünlük sağlamaz.
Yanıt sözleşmesinde neler olmalı?
{
"data": [{"id": 101, "name": "Örnek ürün"}],
"next_cursor": "opaque-cursor-value",
"has_more": true
}
has_more hesabı için uygulamalar bazen istenenden bir fazla kayıt sorgular; fazla kayıt varsa sonuçtan çıkarıp sonraki sayfanın bulunduğunu işaretler. page_size için makul varsayılan ve üst sınır belirleyin. Filtre ve sıralamayı cursor ile uyumlu tutun; istemci filtreyi değiştirirse eski cursor'u kullanmamalıdır.
Hangisini seçmeliyim?
Sayfa numarasına rastgele atlama önemliyse ve veri hacmi uygunsa offset basit bir seçimdir. Sürekli ekleme yapılan akışlarda veya uzun listeleri baştan sona işlerken cursor genellikle daha uygun bir başlangıçtır. Bununla birlikte cursor da tek başına sabit bir anlık görüntü garantisi vermez: kayıtlar silinebilir veya sıralama alanları değişebilir. Tutarlı dışa aktarma gerekiyorsa sınır zamanı, snapshot veya veri tabanına uygun bir başka yaklaşımı ayrıca tasarlayın.
Gerçek bir entegrasyonda sağlayıcının kendi next bağlantısını ya da cursor değerini izleyin; işaretin içeriğini tahmin etmeyin. Sayfalar tamamlanmadan işi başarılı saymayın ve kesintide nereden devam edileceğini planlayın. GitHub'ın REST API sayfalama rehberi, bağlantı başlıklarıyla çalışan bir örnektir.
BİRLİKTE ÖĞRENELİM
Yorumlar
Henüz yorum yok. Düşünceni paylaşarak sohbeti başlatabilirsin.
Bir Yorum Bırak.
Katkılarını ve deneyimlerini duymak isterim. Yorumlar yayınlanmadan önce incelenir.