Hyperf 查询分页实战:数据库 paginate 与分页器组件深度解析

原创2026-10-08 11:56:531,831 阅读
文章标签:后端微服务RPC框架Web框架

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() 的实现分为三步:

  1. 通过 Paginator::resolveCurrentPage($pageName) 解析当前页码(默认 page 参数);
  2. 调用 getCountForPagination() 执行一条 count(*) 聚合查询获取总记录数;
  3. 通过 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 等),可继续阅读 分页 章节;查询构造器与模型的完整用法参见 查询构造器 与 模型。

登录后查看全文
hyperf