Hyperf 查询分页实战:数据库 paginate 与分页器组件深度解析
Hyperf 查询分页实战:数据库 paginate 与分页器组件深度解析
分页是 Web 应用中最常见的数据处理需求之一。在 Hyperf 中,数据库组件 hyperf/database 已与分页器组件 hyperf/paginator 深度集成:你只需在查询构造器或模型查询上调用 paginate() 方法,即可自动读取当前 HTTP 请求中的 page 参数完成分页,并直接以 application/json 格式返回结构化分页结果。读完本文,你将掌握查询构造器与模型两种分页写法、分页器实例的完整方法集、LengthAwarePaginator 与 Paginator 的选型差异,以及分页组件从请求参数解析到 URL 生成的底层实现原理。
分页工作原理与默认行为
通过 查询构造器 或 模型 查询数据时,调用 paginate 方法即可处理分页,该方法会自动根据用户当前查看的页面设置查询的 LIMIT(限制)与 OFFSET(偏移量)。默认情况下,当前页数取自当前 HTTP 请求所带的 page 参数:
- 请求
GET /users?page=2时,page = 2; - 未携带
page参数或参数非法时,默认回落到第 1 页。
注意:由于 Hyperf 当前并不支持服务端视图渲染,分页组件尚未支持对视图的渲染,直接返回分页结果默认会以
application/json格式输出。这意味着分页器可以像普通响应体一样直接return给客户端,无需额外序列化。
这一“自动识别页码”的能力来源于 hyperf/paginator 组件内置的 PageResolverListener:在框架 BootApplication 事件触发时,它会通过 Paginator::currentPageResolver() 注册一个页码解析回调,从当前请求的 page 参数中读取并校验整数页数,同时通过 Paginator::currentPathResolver() 注册当前请求路径解析器,供后续分页 URL 生成使用。
查询构造器分页
在查询构造器上直接调用 paginate($perPage),即可完成分页查询,$perPage 表示每页显示的记录数:
<?php
// 展示应用中的所有用户,每页显示 10 条数据
return Db::table('users')->paginate(10);
从源码看,Query\Builder::paginate() 的实现分为三步:
- 通过
Paginator::resolveCurrentPage($pageName)解析当前页码(默认page参数); - 调用
getCountForPagination()执行一条count(*)聚合查询获取总记录数; - 通过
forPage($page, $perPage)生成带LIMIT/OFFSET的查询并执行get($columns)获取当前页数据,最终构造一个LengthAwarePaginator返回。
因此 paginate() 会执行 两条 SQL(一条计数、一条取数),并返回包含 total、last_page 等完整信息的长度感知分页器。
模型分页
基础用法
模型查询同样支持直接通过静态方法调用 paginate 进行分页:
<?php
// 展示应用中的所有用户,每页显示 10 条数据
return User::paginate(10);
带条件分页
你可以在分页前追加查询条件或其它查询设置方法,链式调用完全兼容:
<?php
// 展示应用中的所有用户,每页显示 10 条数据
return User::where('gender', 1)->paginate(10);
在 Model\Builder::paginate() 中,每页数量 $perPage 为空时会回落到模型上配置的 $perPage 属性($this->model->getPerPage(),默认 15),因此即使不传参数也能得到一个合理的默认分页行为。
分页器实例方法
paginate() 返回的分页器实例提供了一系列便捷方法,以下是数据库查询场景中最常用的方法及含义:
<?php
// 获取当前页数
$currentPage = $paginator->currentPage();
// 获取当前页的数据条数
$count = $paginator->count();
// 获取当前页中第一条数据的编号(在整个结果集中的位置,从 1 开始)
$firstItem = $paginator->firstItem();
// 获取当前页中最后一条数据的编号
$lastItem = $paginator->lastItem();
// 判断是否还有更多分页
if ($paginator->hasMorePages()) {
// ...
}
// 下一页的 URL
$nextPageUrl = $paginator->nextPageUrl();
// 上一页的 URL
$previousPageUrl = $paginator->previousPageUrl();
// 获取指定 $page 页数的 URL
$url = $paginator->url($page);
// 是否处于第一页
$onFirstPage = $paginator->onFirstPage();
// 是否有更多分页(等价于 hasMorePages)
$hasMorePages = $paginator->hasMorePages();
// 每页的数据条数
$perPage = $paginator->perPage();
其中 firstItem() 与 lastItem() 的计算逻辑在 AbstractPaginator 中有明确定义:firstItem 为 (currentPage - 1) * perPage + 1,lastItem 为 firstItem + count() - 1;当当前页无数据时两者均返回 null。
数据总数需要 LengthAwarePaginator
Hyperf\Paginator\Paginator没有total()方法,需要使用Hyperf\Paginator\LengthAwarePaginator。
<?php
$total = $paginator->total();
total() 由 LengthAwarePaginator 提供,返回的是分页前的结果集总数。这正对应着查询构造器 paginate()(返回 LengthAwarePaginatorInterface)与 simplePaginate()(返回 PaginatorInterface)的差异:只有“长度感知”的分页器才持有 total 与 lastPage 信息,其 toArray() 输出也额外包含 last_page、last_page_url、total 字段。
simplePaginate:轻量分页的另一种选择
当数据量极大、对 COUNT 聚合查询的性能开销敏感时,可以使用 simplePaginate() 进行“无总数”分页:
<?php
// 查询构造器
return Db::table('users')->simplePaginate(10);
// 模型
return User::where('gender', 1)->simplePaginate(10);
其实现见 Query\Builder::simplePaginate():通过 skip(($page - 1) * $perPage)->take($perPage + 1) 多取一条数据来判断是否还有下一页,省去了 COUNT 查询,仅执行一条 SQL。这一点在 ModelRealBuilderTest 中得到了验证——测试断言 simplePaginate(1) 生成的 SQL 为 select * from user limit 2 offset 0(即每页 1 条、多取 1 条以探测下一页)。代价是响应中不包含 total 与 last_page,且由于 Paginator 只能通过“当前页是否取满”判断 hasMore,通常需要搭配“加载更多”类的前端交互使用。
底层原理:页码解析与 URL 生成
页码与路径的自动解析
PageResolverListener 监听 BootApplication 事件,在应用启动时向分页器注册两个静态解析器:
currentPageResolver:从当前请求的page参数取值,经FILTER_VALIDATE_INT校验且>= 1时返回该整数,否则返回默认值1;currentPathResolver:返回当前请求的完整 URL 作为分页链接的基础路径。
这正是 paginate() 无需手动传页码、且生成的 next_page_url 等链接天然携带正确路径的原因。若在非 HTTP 环境(如命令行脚本)使用,两个解析器会分别回落为默认值 1 与 /。
分页 URL 的构造规则
分页链接由 AbstractPaginator::url() 统一生成,其规则为:path + pageName=页码 形式的查询串,并叠加 query(通过 appends() 追加的额外查询参数)与 fragment(锚点)。默认的页码参数名为 page,可通过 setPageName() 修改;基础路径可通过 withPath() / setPath() 指定。此外还提供 appends()(保留如排序等额外查询串)、withQueryString()(自动继承当前请求全部查询串)、onEachSide()(控制相邻页链接数量)等链式方法,便于构造完整的分页导航参数。
JSON 响应结构
paginate() 返回的 LengthAwarePaginator 直接作为响应体返回时,其 toArray() 输出的 JSON 结构为:
{
"current_page": 1,
"data": [],
"first_page_url": "http://host/users?page=1",
"from": 1,
"last_page": 10,
"last_page_url": "http://host/users?page=10",
"next_page_url": "http://host/users?page=2",
"path": "http://host/users",
"per_page": 10,
"prev_page_url": null,
"to": 10,
"total": 100
}
而 simplePaginate() 返回的 Paginator 的 toArray() 则省略了 last_page、last_page_url、total 三个字段。前端可据此直接消费 data 与各分页链接。
独立使用分页器组件
分页需求并不只存在于数据库查询。任何数据集分页场景都可独立安装并使用 hyperf/paginator 组件(该组件也可用于其它框架):
composer require hyperf/paginator
只需存在数据集和分页需求,便可通过实例化 Hyperf\Paginator\Paginator 类进行分页。构造函数签名为 __construct($items, int $perPage, ?int $currentPage = null, array $options = <a href="https://link.gitcode.com/i/adef4bb7f544e5223c553a64de0846c6" target="_blank">]):以 数组(Array) 或 Hyperf\Collection\Collection 集合类的形式传递数据集到 $items 参数,并设定每页数据量 $perPage 与当前页数 $currentPage;$options 参数则可通过 Key-Value 的形式定义分页器实例内的所有属性(如 path、query、fragment、pageName,对应 [Paginator 构造函数 中的属性覆盖逻辑)。
<?php
namespace App\Controller;
use Hyperf\HttpServer\Annotation\AutoController;
use Hyperf\HttpServer\Contract\RequestInterface;
use Hyperf\Paginator\Paginator;
use Hyperf\Collection\Collection;
#[AutoController]
class UserController
{
public function index(RequestInterface $request)
{
$currentPage = (int) $request->input('page', 1);
$perPage = (int) $request->input('per_page', 2);
// 这里根据 $currentPage 和 $perPage 进行数据查询,以下使用 Collection 代替
$collection = new Collection([
['id' => 1, 'name' => 'Tom'],
['id' => 2, 'name' => 'Sam'],
['id' => 3, 'name' => 'Tim'],
['id' => 4, 'name' => 'Joe'],
]);
$users = array_values($collection->forPage($currentPage, $perPage)->toArray());
return new Paginator($users, $perPage, $currentPage);
}
}
注意,Paginator 在构造时会通过 setItems() 将数据集切片到当前页(slice(0, $perPage)),并以“切片后是否仍多于每页条数”推断 hasMore,因此传入的数据集应包含“每页条数 + 1”条数据才能准确判断下一页是否存在;若需要 total()、lastPage() 等总数感知能力,请使用 LengthAwarePaginator。
小结
- 数据库查询分页只需一行:查询构造器或模型调用
paginate($perPage),页码自动来自请求的page参数; - 需要总数与总页数的完整分页信息用
paginate()(LengthAwarePaginator),追求性能、只关心“是否有下一页”时用simplePaginate(); - 分页器实例提供
currentPage()、count()、firstItem()、lastItem()、hasMorePages()、nextPageUrl()、previousPageUrl()、url($page)、onFirstPage()、perPage()、total()(后者仅LengthAwarePaginator)等完整方法; - 页码解析与路径解析由
PageResolverListener在框架启动时自动注册,分页 URL 生成规则与 JSON 响应结构可在 src/paginator/src 目录下进一步阅读源码印证。
关于分页器更多细节(如 URL 窗口、UrlWindow 等),可继续阅读 分页 章节;查询构造器与模型的完整用法参见 查询构造器 与 模型。