api-pagination

用途

API Pagination 用于为大型数据集实现可扩展的分页策略，帮助开发者在返回资源集合时进行高效查询、导航和性能优化。它适合以下场景：返回大量资源集合、实现搜索结果分页、构建无限滚动界面、优化大数据集查询、管理客户端应用内存，以及改善 API 响应时间。

主要能力

该技能提供三种核心分页策略的实现指导：

Offset/Limit 分页：通过页码和每页数量计算偏移量进行分页，示例中包含总数统计和总页数计算。
Cursor-Based（游标）分页：适合大型数据集的分页方式。
Keyset 分页：适合极大数据集的分页方式。

此外还涵盖搜索分页、分页响应格式，以及 Python（SQLAlchemy）分页实现。详细实现位于 references/ 目录下的参考指南中。

使用方式

资料提供了一个 Node.js 的 offset/limit 最小可运行示例：

// 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/ 目录下的对应指南。

参考指南

references/ 目录包含以下详细实现：

指南	内容
Offset/Limit Pagination	Offset/Limit 分页
Cursor-Based Pagination	游标分页
Keyset Pagination	Keyset 分页
Search Pagination	搜索分页
Pagination Response Formats	分页响应格式
Python Pagination (SQLAlchemy)	Python 分页（SQLAlchemy）

最佳实践

建议做法（DO）：

对大型数据集使用游标分页
设置合理的最大限制（例如 100）
在可行时包含总数
提供导航链接
记录分页策略
对排序字段使用索引
适当缓存分页结果
处理边界情况（空结果）
实现一致的分页格式
对极大数据集使用 keyset

避免做法（DON'T）：

对数十亿行使用 offset
允许无限制的页大小
每次请求都统计行数
无排序进行分页
分页中途更改排序顺序
无游标进行深度分页
对大型数据集跳过分页
直接暴露数据库分页
混用分页策略
忽视性能影响

限制

资料未提供关于收费、价格、支持平台或具体性能指标的说明。

技能介绍

用途

主要能力

使用方式

参考指南

最佳实践

限制