Laravel API中如何配置分页查询及设置分页参数的方法？

本文共计794个文字，预计阅读时间需要4分钟。

直接查看数据量和前端需求：

常见错误是默认写 paginate() 却没意识到它会多执行一条 COUNT(*) 查询——当表有千万级数据、又没给分页字段加索引时，接口直接卡住或超时。

• paginate(15) 返回完整分页对象，含 $data->lastPage()、$data->total()
• simplePaginate(15) 只返回当前页数据 + 下一页是否有数据（$data->hasMorePages()）
• Laravel 9+ 中，simplePaginate() 默认使用游标分页逻辑（但不是真正的游标分页，只是省 COUNT）

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

别让前端每次自己拼 next_page_url 和 prev_page_url。Laravel 默认返回的 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，那样会触发 Laravel 自动序列化，links 里混着 HTML 标签，前端解析失败。

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

page 和 per_page 是 URL 查询参数，前端可随意改——比如传 per_page=10000 把整张表拖出来。

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

• 用 request()->integer('page', 1) 强制转整型，避免字符串注入
• 限制 per_page 上限，例如 min(max(request()->integer('per_page', 15), 1), 100)
• 如果业务允许，优先用游标分页（cursorPaginate()），它不依赖 page 数字，天然防跳页攻击

游标分页要求排序字段（如 id）有唯一索引，否则可能漏数据或重复。

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

用户点“下一页”时，URL 里原有的筛选参数（比如 ?status=active&search=john）会消失，除非你显式传递。

Laravel 的 appends() 是最简方案，但它会把所有请求参数都带上——可能泄露敏感字段（如 token 或 debug=true）。

• 安全做法：只追加明确需要的键，$users->appends(request()->only(['status', 'search']))
• 更干净的方式：在响应 meta 里返回带全参数的 next_page_url，而不是依赖前端拼接
• 别在中间件里全局 appends()，容易污染其他分页逻辑

真正麻烦的是带复杂嵌套查询的场景——比如搜索用到了全文索引或关联字段，分页时得确保 WHERE 条件完全一致，否则第 2 页的数据可能和第 1 页重叠或遗漏。