如何详细实现ThinkPHP中的分页响应功能？

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

plaintext在使用分页功能时，请注意以下几点：

分页对象不能直接转 JSON

ThinkPHP 的分页对象（如 User::where()->paginate(10)）内部封装了查询元信息、总数、当前页数据、URL 参数等。一旦调用 $list->toArray() 或 json($list)，它就变成纯数组，所有分页方法（render()、lastPage()、hasPages()）全部不可用。

• 错误写法：return json($list); → 前端收不到分页导航，也拿不到 total 和 per_page
• 正确做法：手动构造响应结构，保留关键分页字段
• 必须显式提取：$list->items()（当前页数据）、$list->total()（总数）、$list->per_page()（每页条数）、$list->current_page()（当前页码）、$list->last_page()（总页数）
• 示例响应结构：

  return json([ 'data' => $list->items(), 'meta' => [ 'total' => $list->total(), 'per_page' => $list->per_page(), 'current_page' => $list->current_page(), 'last_page' => $list->last_page(), 'has_next_page' => $list->hasMore(), ] ]);

API 分页需手动透传 query 参数

Web 页面分页靠 render() 自动拼 URL，但 API 接口不渲染 HTML，翻页链接得由前端自己拼。如果没保留搜索条件或过滤参数，?page=2 一发过去，条件全丢。

• 漏掉 query 配置，$list->currentPage() 能读，但前端无法生成带 keyword=xxx 的下一页 URL
• 必须在 paginate() 时传入：User::where($where)->paginate(10, false, ['query' => request()->param()])
• 注意：request()->param() 包含所有 GET 参数，但若 POST/JSON 请求带筛选条件，得手动提取并塞进 query
• 敏感字段（如 token、sign）建议白名单过滤，避免透传到分页链接里

分页后不能链式调用 where/order

分页对象是查询执行完的结果，不是查询构造器。对它再调 where() 或 order() 没有效果，也不会报错，只是静默失效。

立即学习“PHP免费学习笔记（深入）”；

• 错误写法：$list = User::paginate(10)->where('status', 1); → where() 完全被忽略
• 正确时机：所有 where、order、with 必须在 paginate() 之前完成
• 常见误操作：先 paginate()，再想“加个关联字段”，于是补 ->with('profile') —— 这只会让 items() 里的模型懒加载，但不会影响分页 SQL
• 如需关联预加载，必须写在前面：User::with('profile')->where(...)->paginate(10)

大数据量下 COUNT + OFFSET 是性能杀手

当表记录超 50 万，paginate(10) 默认触发 COUNT(*) 全表扫描 + LIMIT 100000, 10，MySQL 会扫描并丢弃前 10 万行，IO 和 CPU 双重飙升。

• 现象：SELECT COUNT(*) FROM user WHERE status=1 耗时 >1s，page=10000 响应超时
• 不要试图缓存 total() 应对——缓存过期后仍要查，且游标分页根本不需要总数
• 真实解法：改用游标分页（cursor-based），基于主键或时间戳推进：->where('id', '>', $last_id)->limit(10)
• 注意 order 方向必须匹配：> 对应 ORDER BY id ASC； 对应 <code>ORDER BY id DESC
• 游标分页无法跳页（不支持 page=100），但对“加载更多”场景更稳更快

分页不是套个方法就完事，核心在于理解它背后是「先 COUNT 再 LIMIT」两个 SQL 的协同；而 API 场景下，最容易被忽略的是：你把它当数据返回，却忘了它本是个带行为的对象。