如何在 Laravel 中基于查询参数实现正确的 20 条/页分页逻辑

本文详解如何修复基于 `offset` 查询参数的手动分页逻辑错误，指出原始代码中页码与偏移量混淆的问题，并提供使用集合 `chunk()` 或标准数学计算两种可靠方案。

在 Laravel（或纯 PHP）中对本地数组或 API 响应结果进行客户端分页时，一个常见误区是将查询参数名（如 offSet）误当作“页码”（page number）来处理，而实际上它通常代表的是起始偏移量（zero-based index）——即从第几条记录开始取数据。

你提供的代码中存在两个关键问题：

1. 参数语义混淆：$request->get('offSet') 返回的是偏移量（如 0, 20, 40），但你却用它当作页码（$page = 1）参与计算：$skip = ($page - 1) * $take。这导致当 offSet=2 时，$skip = (2-1)*20 = 20，实际跳过了前 20 条，却误以为是“第 2 页”，而真正的第 2 页本应从索引 20 开始——表面看似巧合正确，但逻辑已错位；一旦传入 offSet=2（非倍数）就会严重错乱。

2. 边界安全缺失：未校验 $skip 是否超出集合长度，也未处理负数、非数字等非法输入，易导致空结果或报错。

✅ 正确做法有两种主流方案：

方案一：按真实 offset 直接切片（推荐，语义清晰）

$offset = (int) $request->input('offSet', 0);
$take = 20;

// 确保 offset 非负且不越界
$offset = max(0, $offset);
$results = collect($response->json()['results']);
$paginationResults = $results->slice($offset, $take)->values()->all();

✅ 优势：语义准确（offSet=0 → 第 1 页，offSet=20 → 第 2 页），性能好（O(1) 跳过，无需 chunk 全量内存）。

方案二：使用 chunk()（仅适用于小数据集）

$chunkIndex = (int) $request->input('offSet', 0);
$results = collect($response->json()['results']);
$chunks = $results->chunk(20);

// 安全获取指定块，越界返回空数组
$paginationResults = $chunks->get($chunkIndex, collect())->all();

⚠️ 注意：chunk() 会将整个集合拆分为多个子集合，内存开销随数据量线性增长，不适用于上千条以上的结果；且 offSet=2 表示取第 3 个 chunk（即第 3 页），与常规 REST 分页习惯不符，易引发歧义。

✅ 最佳实践建议

• 统一使用标准分页参数名：?page=1&per_page=20（服务端计算 offset），或 ?offset=0&limit=20（客户端明确控制）；
• 始终对输入做类型转换和范围校验；
• 对空结果或越界情况返回一致结构（如 [] 或带 total: 0 的响应）；
• 如数据量大，优先在 API 层完成分页（如数据库 LIMIT/OFFSET），避免在应用层加载全部结果。

修正后，无论传入 offSet=0、20、40 还是 199，都能稳定、可预测地返回对应批次的最多 20 条数据。