ThinkPHP8.1接口分页数据返回实现教程-ThinkPHP-PHP中文网

thinkphp 8.1 接口分页返回需用 paginator 统一 json 结构，显式控制 page/limit 参数并校验边界，提取 data、pagination 元信息，封装助手方法提升复用性。

thinkphp8.1接口分页数据返回实现教程

ThinkPHP 8.1 中实现接口分页数据返回，核心是使用 Paginator（分页器）配合 JSON 格式输出，避免模板渲染，重点在于统一结构、兼容前端分页组件、正确处理参数和异常。

一、基础分页查询（支持 limit + offset 或 page 模式）

TP8.1 默认推荐使用 paginate() 方法，它会自动识别请求中的 page 和 list_rows（每页条数）参数。接口中建议显式传参，提升可控性：

直接调用模型的 paginate()，例如：UserModel::where('status', 1)->paginate(15, false, ['query' => request()->param()]);
false 表示不自动获取当前页码，改由手动控制；['query' => ...] 确保分页链接（如上一页/下一页）携带原始查询参数，对 API 虽不生成 HTML 链接，但能保证 render() 兼容性和调试友好
若需基于 offset/limit（如 App 常用方式），可手动计算：$page = max(1, (int)input('page', 1)); $limit = min(100, (int)input('limit', 10)); $offset = ($page - 1) * $limit;，再用 limit($limit)->offset($offset) 查询，并自行构造分页信息

二、统一 JSON 返回结构（含分页元信息）

接口不应直接输出 Paginator 对象（含大量冗余属性），应提取关键字段组装标准结构：

PHP 8.5.12 RC 1

PHP 8.5.12 RC 1 候选版修复 BZ2、DOM、PDO、Opcache/JIT 和扩展内存安全问题，改进 Unicode 字素处理、URL 解析、TLS 流状态、信号分发及会话错误处理。

下载

常用字段包括：data（当前页数据列表）、current_page、last_page、per_page、total、has_next_page、has_prev_page

示例组装代码：

$paginated = UserModel::paginate(10);<br>
$data = $paginated->items();<br>
$result = [<br>
  'data' => $data,<br>
  'pagination' => [<br>
    'current_page' => $paginated->currentPage(),<br>
    'last_page' => $paginated->lastPage(),<br>
    'per_page' => $paginated->listRows(),<br>
    'total' => $paginated->total(),<br>
    'has_next_page' => $paginated->hasMore(),<br>
    'has_prev_page' => $paginated->currentPage() > 1<br>
  ]<br>
];<br>
return json($result);

三、处理分页参数与异常边界

用户可能传非法 page 或极大 limit，需主动拦截：

限制页码最小为 1，最大建议不超过 1000（防深度遍历）；限制每页最多 100 条，防止 OOM 或慢查询：$page = max(1, min(1000, (int)input('page', 1))); $limit = max(1, min(100, (int)input('limit', 10)));
空数据时，paginate() 仍返回有效分页对象，items() 为空数组，无需特殊判断；但若总数为 0 应确保 last_page === 0 或 1，TP8.1 默认为 1，符合常规理解
数据库查询失败（如字段不存在）会抛异常，建议在控制器中 try-catch 并返回 500 或自定义错误码，避免裸错暴露