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

概述 - 目标：避免`OFFSET`深分页导致的性能问题，采用游标与稳定排序实现高效分页与精确定位。 - 适用：订单列表、消息时间线、用户内容流等海量数据分页。 核心与实战 - 稳定排序字段： - 选择唯一且随时间单调的组合，如`created_at DESC, id DESC`。 - 响应结构示例： ``` HTTP/1.1 200 OK Content-Type: application/json Link: ; 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("|") // 客户端仅透传，服务端解析出排序锚点 ``` - 错误处理与边界： ``` -- 当数据不足一页时，返回next_cursor为空；Link头不包含next ``` 验证与监控 - 一致性： - 校验排序稳定性与去重；保证新写入不会影响历史页顺序。 - 指标： - 记录`next/prev`命中率与平均扫描行数；观察延迟与错误率。 - 兼容性： - 同时支持`before`游标实现向前翻页；保证令牌短期有效并签名防篡改。 常见误区 - 使用`OFFSET`做深分页导致扫描与内存消耗大；应改为游标条件。 - 游标使用非唯一字段造成重复或遗漏；必须使用唯一稳定组合。 - 暴露可解析游标导致客户端构造越界请求；应使用不透明令牌并校验签名。 结语 - 游标化分页以稳定排序为基石，能在高并发场景保持性能与一致性，配合Link头与不透明令牌提升可用性。