Hyperf 数据库查询分页实战:paginate 方法、分页器组件与底层实现剖析

原创2026-10-10 23:46:571,826 阅读
文章标签:后端微服务RPC框架Web框架

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,
    ]);
}

整个流程可以拆解为三步:

  1. 解析当前页:通过 Paginator::resolveCurrentPage($pageName) 读取请求中的 page 参数(未传则默认为第 1 页)。
  2. 统计总数:调用 getCountForPagination() 执行一次 COUNT(*) 聚合查询(若查询包含 group by 或 having,则会走克隆查询的 runPaginationCountQuery() 分支,见 Query/Builder.php),得到数据总条数;若总数为 0,则直接返回空集合,避免无谓的查询。
  3. 截取当前页数据:通过 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):

  1. 判断 items->count() > perPage,得出 hasMore(是否有更多页);
  2. 通过 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() 等更多实例方法,将分页能力灵活地嵌入到自己的业务组件中。

登录后查看全文
hyperf