LaravelAPI如何实现分页_LaravelAPI分页查询设置【方法】

先看数据量，再看前端想怎么展示——这其实是分页方案取舍的核心逻辑。 先说个实际场景：如果业务需要显示“第 1 页 / 共 20 页”并支持跳到任意页码，那就必须用 `paginate()`，因为它会额外执行一条 `COUNT(*)` 来算总数；但如果交互只要求“上一页 / 下一页”的滚动加载（比如无限滚动、时间线），`simplePaginate()` 无疑是更轻量的选择，它根本不查总数，只告诉你“还有没有下一页”。 很多团队默认就写 `paginate()`，却没意识到这条 `COUNT` 查询的代价。当表里有千万行数据、分页字段也没加索引时，接口往往会直接卡住或超时。这本身不是 `paginate()` 的错，而是没根据场景做取舍。

分页函数用 paginate() 还是 simplePaginate()？

怎么选？直接看数据量和前端需求：
- 如果必须展示总页数、允许跳转到任意页 → 用 paginate()。
- 如果只做“上一页/下一页”滚动加载（比如无限滚动） → 用 simplePaginate()，更快，因为它不查总数。

举个例子：
- paginate(15) 会返回完整分页对象，包含 $data->lastPage()、$data->total() 等全部元数据。
- simplePaginate(15) 只返回当前页数据和 $data->hasMorePages()，告诉你是否还有下一页。
- 值得一提的是，Lara vel 9+ 的 simplePaginate() 默认使用了游标风格的分页逻辑——不过说到底，它的核心优势在于省掉那个 COUNT 查询。

API 分页响应结构怎么统一？

别把分页元数据的拼接责任丢给前端。Lara vel 默认的 links 包含的是 HTML 字符串，对 API 场景基本没用。

正确的做法是手动构建 JSON 响应，把分页元信息扁平化，让前端拿到就能直接用：

return response()->json([    'data' => $users,    'meta' => [        'current_page' => $users->currentPage(),        'last_page' => $users->lastPage(),        'per_page' => $users->perPage(),        'total' => $users->total(),        'from' => $users->firstItem(),        'to' => $users->lastItem(),    ]]);

注意一点：千万不要直接 return $users。那样会触发 Lara vel 的自动序列化，结果里会混入 HTML 标签，前端解析时必然报错。

如何避免分页参数被恶意篡改？

page 和 per_page 本来就是 URL 参数，前端可以随意修改。如果传一个 per_page=10000，服务端不做限制的话，整张表就会被一次性拉出来。

必须在控制器层做校验和截断：

• 用 request()->integer('page', 1) 强制转为整型，防止字符串注入。
• 对 per_page 设置上限，比如 min(max(request()->integer('per_page', 15), 1), 100)。
• 如果业务允许，大力推荐用游标分页（cursorPaginate()）。它的好处是不依赖页码数字，天然防御跳页攻击。

但游标分页也有前提：排序字段（如 id）必须建有唯一索引，否则可能出现数据遗漏或重复。

分页后怎么保持查询条件不丢失？

用户点“下一页”时，URL 里原有的筛选参数（比如 ?status=active&search=john）如果不做处理会自然丢失，除非你手动带上它们。

Lara vel 的 appends() 是最直接的方案，但它默认会把所有请求参数都带过去——这可能暴露敏感字段（如 token 或 debug=true）。

更安全的做法是只追加你明确需要的键：

$users->appends(request()->only(['status', 'search']));

更干净的方式是在响应 meta 里直接返回带全参数的 next_page_url，由后端拼接好，前端只需要按地址请求就行。

还需要注意：不要在中间件里全局调用 appends()，那很容易污染其他不相关的分页逻辑。

真正让人头疼的情况是带有复杂嵌套查询的场景——比如用到了全文索引或关联字段。此时分页必须确保 WHERE 条件完全一致，否则第二页的数据可能与第一页重叠或遗漏，那不是单纯靠 appends() 能解决的。