使用Guzzle Services开发API消费库时实现分页：当前是否有内置功能支持？

好问题！确实，Guzzle早期版本里的Guzzle\Service\Resource\ResourceIterator已经被移除了，但现在我们依然可以用Guzzle的原生组件结合PHP的迭代器特性，优雅地封装分页逻辑，完全不用依赖第三方扩展。

我之前在构建类似的API客户端库时，采用的是实现PHP原生Iterator接口的方式，把分页逻辑封装在一个自定义迭代器里，这样调用方可以直接用foreach遍历所有结果，完全不用关心底层的limit/offset参数处理。下面是具体的实现思路和示例：

1. 自定义分页迭代器类 #

创建一个实现PHP Iterator接口的类，把Guzzle客户端、API端点、分页参数都封装进去，迭代器会自动处理翻页逻辑：

use GuzzleHttp\Client;
use GuzzleHttp\Exception\GuzzleException;

class ApiPaginator implements \Iterator
{
    private Client $client;
    private string $endpoint;
    private int $limit;
    private int $offset = 0;
    private int $total = 0;
    private array $currentItems = [];
    private int $position = 0;
    private array $additionalParams = [];

    public function __construct(Client $client, string $endpoint, int $limit = 20, array $additionalParams = [])
    {
        $this->client = $client;
        $this->endpoint = $endpoint;
        $this->limit = $limit;
        $this->additionalParams = $additionalParams;
    }

    public function rewind(): void
    {
        $this->offset = 0;
        $this->position = 0;
        $this->currentItems = $this->fetchPage();
    }

    public function current(): mixed
    {
        return $this->currentItems[$this->position];
    }

    public function key(): int
    {
        return $this->offset + $this->position;
    }

    public function next(): void
    {
        $this->position++;
        // 当前页的条目遍历完了，自动获取下一页
        if ($this->position >= count($this->currentItems) && $this->offset + $this->limit < $this->total) {
            $this->offset += $this->limit;
            $this->position = 0;
            $this->currentItems = $this->fetchPage();
        }
    }

    public function valid(): bool
    {
        return isset($this->currentItems[$this->position]) && ($this->offset + $this->position) < $this->total;
    }

    /**
     * 调用API获取单页数据
     * @return array
     * @throws GuzzleException
     */
    private function fetchPage(): array
    {
        $response = $this->client->get($this->endpoint, [
            'query' => array_merge($this->additionalParams, [
                'limit' => $this->limit,
                'offset' => $this->offset
            ])
        ]);

        $data = json_decode($response->getBody()->getContents(), true);
        
        // 更新总条数（根据API返回的字段名调整，比如total_count）
        $this->total = $data['total'] ?? 0;
        
        // 返回当前页的条目数组（根据API返回的字段名调整，比如data）
        return $data['items'] ?? [];
    }

    // 额外：支持直接跳转到指定页码（如果API返回了页码字段）
    public function setPage(int $page): void
    {
        $this->offset = ($page - 1) * $this->limit;
        $this->position = 0;
        $this->currentItems = $this->fetchPage();
    }

    public function getTotal(): int
    {
        return $this->total;
    }
}

2. 在你的API库中集成迭代器 #

在Guzzle Services的客户端类里，添加一个返回该迭代器的方法，让调用方可以直接使用：

class YourApiClient
{
    private Client $client;

    public function __construct(Client $client)
    {
        $this->client = $client;
    }

    public function listUsers(int $limit = 20, array $filters = []): ApiPaginator
    {
        return new ApiPaginator(
            $this->client,
            '/api/users',
            $limit,
            $filters
        );
    }
}

3. 调用方的使用方式 #

调用方完全不用关心分页细节，直接用foreach遍历所有结果即可：

$apiClient = new YourApiClient(new Client(['base_uri' => 'https://your-api.com']));
$users = $apiClient->listUsers(20, ['status' => 'active']);

// 遍历所有用户（自动翻页）
foreach ($users as $user) {
    echo $user['name'] . PHP_EOL;
}

// 也可以直接获取总条数
echo "总共有 {$users->getTotal()} 个用户";

为什么这是最合适的方案？ #

• 完全基于Guzzle原生客户端和PHP标准库，没有额外依赖
• 迭代器的方式符合PHP的遍历习惯，调用方使用成本极低
• 可以灵活扩展（比如添加异步分页、缓存页面等）
• 完美适配你提到的limit/offset分页模式，同时支持API返回的页码和总数字段

内容的提问来源于stack exchange，提问作者Alex