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

概述目标：避免`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头与不透明令牌提升可用性。