Hyperf 3.1 的 ORM chunk 方法默认不支持游标分页,因其基于主键 ID 偏移分页,无法应对高并发写入、软删除或时间序消费场景;需手动实现基于 created_at + id 的有序游标分页,并确保索引、非空、时区一致。

Hyperf 3.1 在协程环境下使用 ORM 的 chunk 方法处理大数据分批读取时,**默认不支持游标分页(cursor-based pagination)**,因为 chunk 基于主键自增 ID 的偏移式分页(WHERE id > ? LIMIT N),而游标分页需依赖有序、唯一、不可变的字段(如 created_at + id)来避免翻页错漏和重复数据。在高并发写入场景下,单纯用 ID 分页易因新记录插入导致跳过或重复;游标分页更稳定,但需手动实现。
为什么 chunk 不适合直接做游标分页
Model::chunk($count, $callback) 内部本质是:
– 查询最小 ID → 取一批 → 记录最大 ID → 下次 WHERE id > max_id
– 依赖主键单调递增、无删除/更新干扰
– 无法按时间字段排序后分页,也不支持复合游标(如 created_at, id)
一旦表中存在软删除、ID 不连续、或按时间顺序消费(如消息流、日志归档),原生 chunk 就会出问题。
协程安全的游标分页实现方案
在 Hyperf 3.1 协程环境中,推荐用「手动游标循环 + 每次查询显式 ORDER BY + LIMIT」方式,确保:
- 每次查询都带
ORDER BY created_at ASC, id ASC(或你选定的唯一有序字段组合) - 游标值从上一批最后一条记录提取,如
['created_at' => '2024-01-01 10:00:00', 'id' => 10086] - 下次查询条件为:
WHERE (created_at, id) > (?, ?) ORDER BY created_at, id LIMIT N(MySQL 8.0+ 支持行比较) - 低版本 MySQL 可退化为:
WHERE created_at > ? OR (created_at = ? AND id > ?) - 每次查询在独立协程内执行,避免阻塞;用
Co\Channel或Swoole\Coroutine\WaitGroup控制并发批次
代码示例:基于 created_at + id 的游标分页遍历
以下为可直接复用的核心逻辑(适配 Hyperf 3.1 + Db + Coroutine):
// 假设模型为 Message,按 created_at 升序消费
use Hyperf\DbConnection\Db;
$limit = 1000;
$cursor = null; // 初始为空,首次查最小值
$stop = false;
while (!$stop) {
$builder = Message::query()->orderBy('created_at', 'asc')->orderBy('id', 'asc');
if ($cursor) {
// MySQL 8.0+ 推荐写法(原子、简洁)
$builder->whereRaw('(created_at, id) > (?, ?)', [$cursor['created_at'], $cursor['id']]);
// 兼容旧版 MySQL 可用:
// $builder->where(function ($q) use ($cursor) {
// $q->where('created_at', '>', $cursor['created_at'])
// ->orWhere(function ($q2) use ($cursor) {
// $q2->where('created_at', '=', $cursor['created_at'])
// ->where('id', '>', $cursor['id']);
// });
// });
}
$rows = $builder->limit($limit)->get()->toArray();
if ($rows === []) {
$stop = true;
break;
}
// 处理当前批次(协程内可 await 异步操作)
foreach ($rows as $row) {
go(function () use ($row) {
// 模拟异步处理:调用 HTTP、写 Redis、发消息等
\Hyperf\Coroutine\co::sleep(0.01);
// do something...
});
}
// 更新游标为本批最后一条
$last = end($rows);
$cursor = [
'created_at' => $last['created_at'],
'id' => $last['id'],
];
}
注意事项与优化建议
-
索引必须覆盖游标字段:例如
INDEX idx_cursor (created_at, id),否则性能急剧下降 - 避免 SELECT *:只查必要字段,减少协程内存占用和网络开销
-
游标字段不能为 NULL:否则
(a,b) > (NULL,1)行为不确定,建议 created_at 设为 NOT NULL DEFAULT CURRENT_TIMESTAMP - 注意时区一致性:PHP、MySQL、ORM 配置的时区需统一,避免游标时间错位
- 超时与断点续传:将当前游标存入 Redis 或数据库,异常中断后可从中断点继续,而非从头开始











