3. 分页基础概念
在行情接口的实战开发中，分页不是“可选优化”，而是必须优先设计的基础能力。行情数据具有高频、持续写入、数据量巨大、查询维度多等特点。如果不分页，一次请求可能返回几十万甚至上百万条K线、逐笔成交或盘口快照，既会拖垮服务端数据库，也会让客户端内存暴涨、网络超时、重试成本急剧上升。因此，理解分页的本质与不同分页策略的差异，是构建稳定行情接口的第一步。
核心结论：分页的本质是“在持续变化的数据集中，稳定、可重复地取出一段数据”。偏移分页适合静态或小数据量场景；游标分页、时间戳分页与键集分页更适合高频写入、实时性强的行情数据。
一、为什么行情接口必须分页
行情数据的分页需求来自四个现实约束。第一，数据规模大：一个热门交易对的逐笔成交每天可达数百万条，K线在多个周期下也会快速累积。第二，数据持续写入：新成交、新快照不断产生，结果集在两次请求之间就可能发生变化。第三，网络与内存有限：客户端无法一次性接收并渲染海量数据。第四，接口需要可恢复：当请求失败或限流时，客户端必须能从上次位置继续拉取，而不是从头开始。
如果忽略分页，常见后果包括：数据库全表扫描导致慢查询；接口响应时间从毫秒级恶化到秒级；客户端因超时触发重试，进一步放大服务端压力；在限流场景下，大分页请求更容易被拒绝，形成恶性循环。因此，分页设计直接决定了行情接口的吞吐能力与稳定性。
二、五类分页策略的原理与对比
下面从“定位方式”和“对数据变化的敏感度”两个角度，对偏移分页、游标分页、时间戳分页与键集分页进行对比。需要说明的是，游标分页是一个统称，时间戳分页和键集分页是它在行情场景中最常见的两种具体实现。
| 分页方式 | 定位依据 | 典型参数 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|---|---|
| 偏移分页 | 跳过前N条 | offset、limit | 实现简单、可跳页 | 深分页慢、数据漂移 | 静态历史数据、后台管理 |
| 游标分页 | 服务端返回游标 | cursor、limit | 稳定、不暴露内部结构 | 不能随机跳页 | 通用实时列表 |
| 时间戳分页 | 时间范围 | start_time、end_time | 语义直观、易对齐K线 | 同时间点多条时需去重 | K线、快照、按时间查询 |
| 键集分页 | 排序键比较 | last_id、last_time | 深分页性能好、稳定 | 依赖唯一有序键 | 逐笔成交、订单流水 |
偏移分页的SQL通常写作 LIMIT 20 OFFSET 10000。它的致命问题在于：数据库仍需扫描并丢弃前10000条，偏移越大越慢；同时，如果期间有新数据插入，原本第2页的数据可能被挤到第3页，造成重复或遗漏。行情接口中，这种“数据漂移”会直接导致K线拼接错误。
键集分页则利用“上一页最后一条记录的排序键”作为下一页起点，例如 WHERE trade_id > 100230 LIMIT 20。由于可以直接走索引定位，深分页性能几乎不随页数下降，且不会因为前面插入新数据而漂移。时间戳分页是键集分页在时间维度上的特例，例如 WHERE ts >= 1700000000000 AND ts < 1700000060000，非常适合按分钟、小时聚合的K线查询。
三、方法流程：如何为行情接口选择分页方式
- 明确数据特征：判断数据是静态历史还是持续写入，是否存在唯一递增主键或时间戳。
- 确定查询维度：按交易对、周期、时间范围还是按成交序号查询。
- 选择定位键：优先选择唯一、有序、有索引的字段，如 trade_id、ts、seq。
- 设计返回结构：返回数据列表加下一页游标或结束标记，避免客户端自行计算偏移。
- 处理边界：空结果、重复时间戳、跨页去重、限流后的续传位置都要明确。
- 压测验证：重点测试深分页耗时、并发写入下的重复率与遗漏率。
一个典型的键集分页请求与响应可以设计为：
GET /api/v1/trades?symbol=BTCUSDT&limit=100&last_id=987654321
{
"code": 0,
"data": [
{"trade_id": 987654322, "price": "43210.5", "qty": "0.01", "ts": 1700000000123},
{"trade_id": 987654323, "price": "43211.0", "qty": "0.02", "ts": 1700000000456}
],
"next_cursor": "987654323",
"has_more": true
}客户端只需保存 next_cursor，下次请求原样带回即可。这样即使期间有新成交写入，也不会影响已取数据的连续性。
四、案例与场景：K线与逐笔成交的分页差异
K线数据通常按时间聚合，适合时间戳分页。例如查询1分钟K线，可以按 start_time 和 end_time 切分窗口，每次返回固定数量。由于同一分钟只有一条K线，时间戳天然唯一，分页稳定且易于缓存。
逐笔成交则不同：同一毫秒内可能有多笔成交，时间戳不唯一。此时应使用键集分页，以 trade_id 作为排序键。若业务必须按时间查询，则需要组合条件 WHERE ts >= ? AND trade_id > ?，避免同一时间点数据被截断。
实践建议：行情接口对外暴露统一的分页协议，内部根据数据类型选择偏移、时间戳或键集实现。这样客户端无需关心底层差异，服务端也能灵活优化。
五、误区与复盘
- 误区一：所有分页都用 offset。深分页性能差且数据漂移，行情场景应尽量避免。
- 误区二：游标就是页码。游标应是不透明字符串，客户端不应解析其内部结构。
- 误区三：时间戳一定唯一。高频行情中同一时间戳可能对应多条记录，必须配合唯一键去重。
- 误区四：忽略限流与重试。分页请求应携带幂等游标，重试时从同一位置继续，避免重复消费。
复盘要点：分页设计要与限流、重试策略一起考虑。若游标在重试时丢失，客户端可能重复拉取或跳过数据。建议将游标与请求ID一起记录在日志中，便于排障与对账。
总结来看，偏移分页胜在简单，却难以应对行情的高频写入；游标分页提供了稳定的抽象；时间戳分页贴合K线语义；键集分页则在逐笔成交等深分页场景中表现最佳。理解它们的定位方式与漂移特性，才能在后续的限流与重试实战中做出正确取舍。