本文详解如何通过服务端分页（基于游标或偏移量）与客户端分批处理，规避因单次请求数据量过大引发的 503 service unavailable 错误，适用于百万级记录的高效、稳定拉取场景。
本文详解如何通过服务端分页（基于游标或偏移量）与客户端分批处理，规避因单次请求数据量过大引发的 503 service unavailable 错误，适用于百万级记录的高效、稳定拉取场景。
在调用 REST API 批量获取海量数据（如 160 万条记录）时，若采用固定 pageSize=25000 的循环拉取方式，极易触发网关超时、后端资源耗尽或负载均衡器主动中断连接，最终返回 503 错误——尤其当 Postman 能成功而应用端失败时，往往说明问题不在接口本身，而在客户端请求模式与服务端承载能力不匹配。
根本原因在于：单次请求 25,000 条记录虽看似可控，但持续高频调用会累积数据库压力（如全表扫描、内存排序、连接池占满）、阻塞线程池，并可能被反爬/限流中间件识别为异常流量。更关键的是，若缺乏状态追踪（如未使用游标），重复拉取或跳过数据的风险极高。
✅ 推荐解决方案：服务端游标分页 + 客户端内存分批处理
一、优先采用游标分页（Cursor-based Pagination）
替代传统的 ?page=1&size=25000，服务端应支持基于排序字段（如 created_at, id）的游标参数：
POST /api/v1/orders
Content-Type: application/json
{
"limit": 25000,
"cursor": "2024-05-20T10:30:45.123Z" // 上一页最后一条记录的 created_at
}服务端逻辑示例（伪代码）：
-- 假设按 created_at 升序分页 SELECT * FROM orders WHERE created_at > '2024-05-20T10:30:45.123Z' ORDER BY created_at ASC LIMIT 25000;
✅ 优势：无深度分页性能衰减（避免 OFFSET 越大越慢）、结果严格有序、天然支持断点续传。
二、客户端分批消费，控制内存与吞吐
即使单次响应 25,000 条，也不建议一次性加载至内存处理。应拆分为小批次（如每 1,000 条为一组）进行解析、转换或写入：
async function fetchAllRecords() {
let cursor = null;
const allData = [];
while (true) {
const res = await fetch('/api/v1/orders', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ limit: 25000, cursor })
});
const { data, next_cursor } = await res.json();
// 分批处理：每 1000 条执行一次业务逻辑
for (let i = 0; i < data.length; i += 1000) {
const batch = data.slice(i, i + 1000);
await processBatch(batch); // 如存入 DB、发 Kafka、生成报表
}
if (!next_cursor) break;
cursor = next_cursor;
}
}三、关键注意事项
- 服务端必须提供稳定排序字段：不可依赖无索引字段（如 name），否则游标失效或漏数；
- 避免时间戳精度陷阱：若多条记录 created_at 相同，需追加唯一字段（如 id）作为二级排序，防止游标跳跃；
- 设置合理超时与重试：HTTP 超时建议 ≥30s，重试策略应含指数退避（如 1s → 2s → 4s），并跳过已成功批次；
- 监控与日志：记录每次请求的 cursor、响应时间、数据量，便于定位卡点（如某游标处持续失败，可能对应脏数据）；
- Postman 成功 ≠ 应用可用：Postman 无并发、无长连接复用、无内存限制，不能作为生产调用依据。
通过游标分页将“全量拉取”转化为“增量流式获取”，再辅以客户端轻量分批，可彻底规避 503 错误，同时提升系统稳定性与可扩展性——这是处理百万级数据同步的工业级实践标准。
