ThinkPHP 8.1 接口分页返回需用 Paginator 统一 JSON 结构，显式控制 page/limit 参数并校验边界，提取 data、pagination 元信息，封装助手方法提升复用性。
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，需主动拦截：
立即学习“PHP免费学习笔记（深入）”；
- 限制页码最小为 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 或自定义错误码，避免裸错暴露
四、可选：封装分页响应助手（复用性强）
在 app/common/Helper.php 或独立服务类中封装通用方法，减少重复代码：
- 定义静态方法如
apiPaginate($query, $perPage = 10, $simple = false)，内部完成参数校验、查询、结构组装 -
$simple = true时可只返回精简分页字段（如仅page,pages,count），适配轻量前端需求 - 支持传入闭包预处理数据项（如隐藏敏感字段、添加额外属性），提升灵活性
