api-pagination

API のページネーション

目次

• 概要
• 使用する場面
• クイックスタート
• リファレンスガイド
• ベストプラクティス

概要

効率的なクエリ、ナビゲーション、パフォーマンスの最適化により、大規模なデータセットを扱うためのスケーラブルなページネーション戦略を実装します。

使用する場面

• 大量のリソースを返す場合
• 検索結果のページネーションを実装する場合
• 無限スクロールのインターフェースを構築する場合
• 大規模なデータセットのクエリを最適化する場合
• クライアントアプリケーションのメモリを管理する場合
• API の応答時間を改善する場合

クイックスタート

最小限の動作する例：

// Node.js offset/limit implementation
app.get('/api/users', async (req, res) => {
  const page = parseInt(req.query.page) || 1;
  const limit = Math.min(parseInt(req.query.limit) || 20, 100); // Max 100
  const offset = (page - 1) * limit;

  try {
    const [users, total] = await Promise.all([
      User.find()
        .skip(offset)
        .limit(limit)
        .select('id email firstName lastName createdAt'),
      User.countDocuments()
    ]);

    const totalPages = Math.ceil(total / limit);

    res.json({
      data: users,
      pagination: {
        page,
        limit,
        total,
        totalPages,
        hasNext: page < totalPages,
// ... (see reference guides for full implementation)

リファレンスガイド

詳細な実装については、references/ ディレクトリを参照してください：

ガイド	内容
オフセット／リミット方式のページネーション	オフセット／リミット方式のページネーション
カーソルベースのページネーション	カーソルベースのページネーション
キ​​ーセットページネーション	キーセットページネーション
検索のページネーション	検索のページネーション
ページネーションの応答形式	ページネーションの応答形式
Python のページネーション（SQLAlchemy）	Python のページネーション（SQLAlchemy）

ベストプラクティス

✅ 推奨事項

• 大規模なデータセットにはカーソルページネーションを使用します
• 妥当な最大件数（例：100）を設定します
• 可能な場合は合計件数を含めます
• ナビゲーションリンクを提供します
• ページネーション戦略を文書化します
• 並べ替えにはインデックス付きのフィールドを使用します
• 適切な場合はページネーションの結果をキャッシュします
• エッジケース（結果が空の場合など）に対応します
• 一貫性のあるページネーション形式を実装します
• 非常に大規模なデータセットにはキーセット方式を使用します

❌ 禁止事項

• 数十億行のデータにオフセットを使用しないでください
• ページサイズを無制限にしないでください
• リクエストごとに行数をカウントしないでください
• 並べ替えなしでページネーションを行わないでください
• ページネーションの途中で並べ替え順を変更しないでください
• カーソルなしで深いページネーションを行わないでください
• 大規模なデータセットでページネーションを省略しないでください
• データベースのページネーションを直接公開しないでください
• 複数のページネーション戦略を混在させないでください
• パフォーマンスへの影響を無視しないでください