API分页与游标设计与实现最佳实践

---

title: API分页与游标设计与实现最佳实践

keywords:

• 分页
• 游标
• Cursor
• Link Header
• 稳定排序
• 深分页

description: 以稳定排序与游标化设计替代深分页，提供可验证的HTTP示例与响应结构，提升性能与一致性。

date: 2025-11-26

categories:

• 文章资讯
• 技术教程

---

概述

• 目标：避免OFFSET深分页导致的性能问题，采用游标与稳定排序实现高效分页与精确定位。
• 适用：订单列表、消息时间线、用户内容流等海量数据分页。

核心与实战

• 稳定排序字段：
• 选择唯一且随时间单调的组合，如created_at DESC, id DESC。
• 响应结构示例：

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://api.example.com/orders?after=2025-11-26T10:00:00Z,ORD-123&limit=50>; rel="next"

{
  "data": [ {"id":"ORD-101", "created_at":"2025-11-26T09:59:59Z"} ],
  "page": {
    "limit": 50,
    "next_cursor": "2025-11-26T10:00:00Z,ORD-123"
  }
}

• 下一页请求示例：

GET /orders?limit=50&after=2025-11-26T10:00:00Z,ORD-123

• 服务器查询逻辑：

-- 条件：created_at < after_ts 或 (created_at = after_ts 且 id < after_id)

示例

• 游标编码（不透明令牌）：

// base64url("<ts>|<id>")
// 客户端仅透传，服务端解析出排序锚点

• 错误处理与边界：

-- 当数据不足一页时，返回next_cursor为空；Link头不包含next

验证与监控

• 一致性：
• 校验排序稳定性与去重；保证新写入不会影响历史页顺序。
• 指标：
• 记录next/prev命中率与平均扫描行数；观察延迟与错误率。
• 兼容性：
• 同时支持before游标实现向前翻页；保证令牌短期有效并签名防篡改。

常见误区

• 使用OFFSET做深分页导致扫描与内存消耗大；应改为游标条件。
• 游标使用非唯一字段造成重复或遗漏；必须使用唯一稳定组合。
• 暴露可解析游标导致客户端构造越界请求；应使用不透明令牌并校验签名。

结语

• 游标化分页以稳定排序为基石，能在高并发场景保持性能与一致性，配合Link头与不透明令牌提升可用性。