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

# 概述 分页是高频接口设计的关键。本文提供游标式分页与稳定排序策略，限制 Offset 深分页、窗口与限流、版本化与一致性策略，并给出验证方法。 # 游标与排序（已验证） - 游标：使用稳定字段（时间+唯一键）生成游标； - 排序：确保不可重复与稳定； - 防止跳页：游标与过滤条件一致。 # Offset 与窗口 - 限制 Offset：避免深分页； - 窗口策略：按时间与大小窗口获取数据； - 限流：限制每页大小与总页数。 # 版本与一致性 - 版本化：游标格式与语义版本； - 一致性：对变动数据采用快照或时间戳过滤； # 示例（片段） ```http GET /orders?cursor=2025-11-26T10:00:00Z|id:123&limit=100 ``` # 验证与监控 - 指标：查询耗时、错误率与翻页成功率； - 对比：Offset 与游标的性能与体验； # 常见误区 - 使用不稳定字段作为排序； - 游标格式不兼容与不可解析； # 结语 以游标与稳定排序为核心，限制 Offset 与窗口、版本化与一致性策略，并以指标验证，API 分页可在高并发下保持性能与可靠性。