Hyperf 数据库查询分页实战:paginate 方法、分页器组件与底层实现剖析
Hyperf 数据库查询分页实战:paginate 方法、分页器组件与底层实现剖析
在使用 hyperf/database 查询数据时,Hyperf 通过分页器组件 hyperf/paginator 提供了开箱即用的查询分页能力:无论是查询构造器还是模型查询,只需调用 paginate() 方法即可自动完成 LIMIT/OFFSET 计算、总条数统计与 JSON 响应生成。本文以数据库查询分页为主线,完整覆盖 paginate 方法的参数与使用姿势,并结合仓库源码深入讲解分页器组件的实例方法、URL 生成原理与响应结构,帮助你写出可维护、可直接落地的分页接口。
分页机制概览:page 参数与自动偏移
Hyperf 的分页设计遵循一个核心约定:paginate 方法会自动根据用户正在查看的页面来设置查询的偏移量(Offset)与限制(Limit)。默认情况下,组件通过当前 HTTP 请求所携带的 page 参数值来检测当前页数,无需你在控制器里手动解析页码。
这里需要特别说明的是,由于 Hyperf 当前并不支持视图(View)渲染,分页器组件尚未支持对视图的渲染。因此,直接返回分页结果时,默认会以 application/json 格式输出,非常适合作为 API 接口的响应载体。
这一“自动检测”行为并非魔法,而是由分页器组件内置的监听器实现的:在 PageResolverListener 中,组件监听框架的 BootApplication 事件,通过依赖容器获取 RequestInterface,并从请求中读取 page 参数:
Paginator::currentPageResolver(function ($pageName = 'page') {
if (! ApplicationContext::hasContainer()
|| ! interface_exists(RequestInterface::class)
|| ! Context::has(ServerRequestInterface::class)
) {
return 1;
}
$container = ApplicationContext::getContainer();
$page = $container->get(RequestInterface::class)->input($pageName);
if (filter_var($page, FILTER_VALIDATE_INT) !== false && (int) $page >= 1) {
return (int) $page;
}
return 1;
});
从 PageResolverListenerTest 的 testPageResolve 用例可以看到这一行为:当请求携带 page=2 时,LengthAwarePaginator 生成的下一页 URL 自动变为 /?page=3,同时 resolveCurrentPath() 也能从请求中解析出当前路径 /index。也就是说,页码解析、当前路径解析都被抽象成了可注入的 Resolver 回调,即使脱离 HTTP 环境(如 CLI 任务),也会安全地回退到默认值 1 与 /。
查询构造器分页
在通过查詢構造器查询数据时,直接对查询构造器调用 paginate 方法即可完成分页:
<?php
// 展示应用中的所有用户,每页显示 10 条数据
return Db::table('users')->paginate(10);
这一行代码的背后,是 Query/Builder.php 中 paginate 方法完整的分页流水线:
public function paginate($perPage = 15, $columns = ['*'], $pageName = 'page', $page = null): LengthAwarePaginatorInterface
{
$page = $page ?: Paginator::resolveCurrentPage($pageName);
$total = $this->getCountForPagination();
$results = $total ? $this->forPage($page, $perPage)->get($columns) : collect();
return $this->paginator($results, $total, $perPage, $page, [
'path' => Paginator::resolveCurrentPath(),
'pageName' => $pageName,
]);
}
整个流程可以拆解为三步:
- 解析当前页:通过
Paginator::resolveCurrentPage($pageName)读取请求中的page参数(未传则默认为第 1 页)。 - 统计总数:调用
getCountForPagination()执行一次COUNT(*)聚合查询(若查询包含group by或having,则会走克隆查询的runPaginationCountQuery()分支,见 Query/Builder.php),得到数据总条数;若总数为 0,则直接返回空集合,避免无谓的查询。 - 截取当前页数据:通过
forPage($page, $perPage)计算出偏移量并执行数据查询。forPage的实现非常简单直观(见 Query/Builder.php):
public function forPage($page, $perPage = 15)
{
return $this->skip(($page - 1) * $perPage)->take($perPage);
}
即 offset = (page - 1) * perPage,limit = perPage——skip 与 take 分别是 offset 与 limit 的别名(见 Query/Builder.php)。
最终,分页器实例并非手动 new 出来的,而是通过依赖容器统一创建:在 BuildsQueries.php 中,paginator() 方法使用 ApplicationContext::getContainer()->make(LengthAwarePaginatorInterface::class, ...) 来实例化。容器绑定关系由分页器组件的 ConfigProvider.php 声明:
'dependencies' => [
PaginatorInterface::class => Paginator::class,
LengthAwarePaginatorInterface::class => LengthAwarePaginator::class,
],
这意味着你可以在自己的代码中通过依赖注入 PaginatorInterface / LengthAwarePaginatorInterface 来获得对应的分页器实现。
模型分页
如果你使用模型查询,同样可以直接通过静态方法调用 paginate 方法来进行分页:
<?php
// 展示应用中的所有用户,每页显示 10 条数据
return User::paginate(10);
当然,你也可以在分页前设置查询条件或其它查询设置方法:
<?php
// 展示应用中的所有用户,每页显示 10 条数据
return User::where('gender', 1)->paginate(10);
模型层的 paginate 实现在 Model/Builder.php,与查询构造器版本相比有两处差异:
- 默认每页条数来自模型:
$perPage为空时使用$this->model->getPerPage()。而模型的默认值定义在 Model.php:
/**
* The number of models to return for pagination.
*/
protected int $perPage = 15;
也就是说,模型的默认每页条数为 15。你可以通过 setPerPage($perPage) 修改,或在子类中覆写 $perPage 属性来调整默认值。
- 查询基于模型 Builder 而非查询构造器:模型 Builder 会先通过
toBase()->getCountForPagination()统计总数,再调用forPage($page, $perPage)->get($columns)查询当前页数据,最后同样交给容器创建LengthAwarePaginator。由于where('gender', 1)等约束已经挂在当前 Builder 上,统计与分页查询都会自动带上这些条件。
paginate 方法参数详解
无论是查询构造器还是模型 Builder,paginate 方法签名都是一致的:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
$perPage |
?int |
构造器:15;模型:$model->getPerPage()(默认 15) |
每页显示的数据条数 |
$columns |
array |
['*'] |
需要查询的列,支持指定列名数组 |
$pageName |
string |
'page' |
查询参数名,用于读取/生成页码,可通过 setPageName() 修改 |
$page |
?int |
null(自动解析) |
当前页数;不传时从请求 pageName 参数解析 |
从 Query/Builder.php 可以看到,还有一个同样重要的姊妹方法 simplePaginate:
public function simplePaginate($perPage = 15, $columns = ['*'], $pageName = 'page', $page = null): PaginatorInterface
{
$page = $page ?: Paginator::resolveCurrentPage($pageName);
$this->skip(($page - 1) * $perPage)->take($perPage + 1);
return $this->simplePaginator($this->get($columns), $perPage, $page, [
'path' => Paginator::resolveCurrentPath(),
'pageName' => $pageName,
]);
}
两者的区别在于:
paginate():返回LengthAwarePaginator(长度感知分页器),会额外执行一次总数统计,因此可以提供total、last_page等完整信息,适合需要渲染页码条的场景。simplePaginate():返回Paginator(简单分页器),不统计总数,只查询perPage + 1条以判断“是否有下一页”,数据量大时效率更高,适合“加载更多”这类只关心上一页/下一页的无限滚动场景。
分页器实例方法
这里仅说明分页器在数据库查询上的使用方法,更多关于分页器组件的细节可阅读分页章节。以下方法对 LengthAwarePaginator 与 Paginator 均适用(total() 除外):
获取当前页数
<?php
$currentPage = $paginator->currentPage();
获取当前页的条数
<?php
$count = $paginator->count();
获取当前页中第一条数据的编号
<?php
$firstItem = $paginator->firstItem();
获取当前页中最后一条数据的编号
<?php
$lastItem = $paginator->lastItem();
这两个编号在 AbstractPaginator.php 中的计算逻辑为:firstItem = (currentPage - 1) * perPage + 1,lastItem = firstItem + count() - 1;当当前页无数据时返回 null。
获取是否还有更多的分页
<?php
if ($paginator->hasMorePages()) {
// ...
}
Paginator(简单分页器)通过“是否查出 perPage + 1 条”来判定(见 Paginator.php 的 setItems);而 LengthAwarePaginator 则通过 currentPage() < lastPage() 精确判断(见 LengthAwarePaginator.php)。
获取对应分页的 URL
<?php
// 下一页的 URL
$nextPageUrl = $paginator->nextPageUrl();
// 上一页的 URL
$previousPageUrl = $paginator->previousPageUrl();
// 获取指定 $page 页数的 URL
$url = $paginator->url($page);
url($page) 是 URL 生成的核心,实现在 AbstractPaginator.php:
public function url(int $page): string
{
if ($page <= 0) {
$page = 1;
}
$parameters = [$this->pageName => $page];
if (count($this->query) > 0) {
$parameters = array_merge($this->query, $parameters);
}
return $this->path . (Str::contains($this->path, '?') ? '&' : '?') . Arr::query($parameters) . $this->buildFragment();
}
它把分页器属性(path、query、fragment、pageName)组合成完整 URL:小于 1 的页码自动规整为 1,额外的查询参数会合并进 URL,路径中已含 ? 时自动改用 & 拼接,并支持追加 URL 片段(Fragment)。
是否处于第一页
<?php
$onFirstPage = $paginator->onFirstPage();
每页的数据条数
<?php
$perPage = $paginator->perPage();
数据总数
Hyperf\Paginator\Paginator 没有这个方法,需要使用 Hyperf\Paginator\LengthAwarePaginator
<?php
$total = $paginator->total();
手动实例化分页器(组件独立使用)
分页器组件并不绑定数据库,只要存在数据集和分页需求,便可直接实例化 Hyperf\Paginator\Paginator 类。该类的构造函数签名为:
__construct($items, int $perPage, ?int $currentPage = null, array $options = [])
只需以数组(Array)或 Hyperf\Collection\Collection 集合类的形式传递数据集到 $items 参数,并设定每页数据量 $perPage 和当前页数 $currentPage 即可;$options 参数则可以通过 Key-Value 的形式定义分页器实例内的所有属性(如 path、query、fragment、pageName),具体可查阅分页器类的内部属性。一个完整的控制器示例:
<?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);
}
}
这里用到了集合的 forPage($currentPage, $perPage) 方法在内存中完成切片,与数据库查询构造器的 forPage 思路一致。在 Paginator.php 的构造函数中,传入的 $items 会被统一包装为 Collection,并自动执行两步处理(见 setItems):
- 判断
items->count() > perPage,得出hasMore(是否有更多页); - 通过
slice(0, perPage)截取当前页数据。
Paginator 实现的 Arrayable / Jsonable / JsonSerializable 接口使得它可以被 json_encode 或直接作为响应返回。若你还需要总数、末页等完整元信息,则实例化 Hyperf\Paginator\LengthAwarePaginator,其构造函数为:
__construct(mixed $items, int $total, int $perPage, ?int $currentPage = 1, array $options = [])
相比 Paginator 多了 $total 参数,lastPage 会通过 max((int) ceil($total / $perPage), 1) 自动计算(见 LengthAwarePaginator.php)。
JSON 响应结构:toArray 与序列化
分页器返回后直接输出,会以 JSON 格式呈现。两种分页器的 toArray() 结构略有差异:
LengthAwarePaginator(paginate 的结果),见 LengthAwarePaginator.php:
{
"current_page": 1,
"data": [],
"first_page_url": "/?page=1",
"from": 1,
"last_page": 3,
"last_page_url": "/?page=3",
"next_page_url": "/?page=2",
"path": "/",
"per_page": 10,
"prev_page_url": null,
"to": 10,
"total": 23
}
Paginator(simplePaginate 的结果),见 Paginator.php,不包含 total、last_page 等字段:
{
"current_page": 1,
"data": [],
"first_page_url": "/?page=1",
"from": 1,
"next_page_url": "/?page=2",
"path": "/",
"per_page": 10,
"prev_page_url": null,
"to": 10
}
from 与 to 即上文所述的 firstItem() 与 lastItem(),表示当前页数据在全量数据集中的编号区间。当你需要在此基础上扩展字段时,可以像任何 Jsonable 对象一样,在返回前通过 paginator->appends()、paginator->withPath() 等方法调整 URL 相关属性(详见下文)。
URL 生成属性:path、query、fragment、pageName
分页器生成 URL 依赖四个核心属性,均可在实例化时通过 $options 传入,或事后通过方法修改:
| 属性 | 默认值 | 作用 | 修改方法 |
|---|---|---|---|
path |
/(HTTP 环境下自动解析为当前请求 URL) |
分页链接的基础路径 | withPath() / setPath() |
query |
[] |
追加到所有分页 URL 的额外查询参数 | appends($key, $value) / withQueryString() |
fragment |
null |
追加到分页 URL 的锚点(#xxx) |
fragment($fragment) |
pageName |
'page' |
页码参数的名称 | setPageName($name) |
这些属性定义在 AbstractPaginator.php。其中 path 在 HTTP 环境下由 PageResolverListener 中的 currentPathResolver 自动解析为当前请求 URL:
Paginator::currentPathResolver(function () {
$default = '/';
// ...
return $container->get(RequestInterface::class)->url();
});
因此分页链接默认会指向当前路由,并携带 ?page=N 参数。如果你需要保留排序、筛选等其它查询参数(例如 ?gender=1&page=2),可以调用 appends() 或 withQueryString()——后者会把当前请求的全部查询串并入分页 URL(实现见 AbstractPaginator.php)。
进阶:游标分页 cursorPaginate
除了基于页码的分页,查询构造器还提供了游标分页方法 cursorPaginate(见 BuildsQueries.php):
public function cursorPaginate(?int $perPage = 15, array|string $columns = ['*'], string $cursorName = 'cursor', null|Cursor|string $cursor = null): CursorPaginatorContract
游标分页不使用页码与偏移量,而是通过编码后的 Cursor(游标)定位数据位置,避免大数据量下 OFFSET 带来的深翻页性能问题。游标的编码/解码实现在 Cursor.php:将排序参数与方向标记序列化为 JSON 后做 Base64 编码,并替换 +、/、= 为 URL 安全的 -、_、空字符;请求中携带的 cursor 参数即可用于翻页。返回的 CursorPaginator 实例(见 CursorPaginator.php)的 JSON 结构为:
{
"data": [],
"path": "/",
"per_page": 15,
"next_cursor": "eyJpZCI6MTV9",
"next_page_url": "/?cursor=eyJpZCI6MTV9",
"prev_cursor": null,
"prev_page_url": null
}
客户端只需把 next_cursor / prev_cursor 作为下一次请求的 cursor 参数回传即可实现翻页。需要注意的是,游标分页要求查询具备稳定的排序字段(通常配合 orderBy 使用),其底层排序参数提取逻辑可参考 BuildsQueries.php 中的 ensureOrderForCursorPagination。
小结
Hyperf 的查询分页由 hyperf/database 与 hyperf/paginator 两个组件协同完成:前者在查询层负责总数统计与 LIMIT/OFFSET 截取,后者在结果层负责页码解析、URL 生成与 JSON 序列化。实践中的选择建议如下:
- 需要总数、末页等完整信息(如后台列表页):使用
paginate(),返回LengthAwarePaginator; - 只需要“上一页 / 下一页”(如移动端无限滚动):使用
simplePaginate(),返回轻量的Paginator,省去总数统计的开销; - 数据量大、深度翻页性能敏感:使用
cursorPaginate()游标分页,基于游标而非偏移量定位; - 在 CLI、队列等非 HTTP 场景中,
paginate()依然可用,页码会自动回退为第 1 页。
通过阅读 分页器组件文档 与 src/paginator 目录下的源码,你还可以进一步掌握 onEachSide()、getUrlRange()、render() 等更多实例方法,将分页能力灵活地嵌入到自己的业务组件中。