当前位置：首页 > 文章列表 > 文章 > php教程 > 用 Fiber 封装可暂停任务：启动、挂起与异常恢复

用 Fiber 封装可暂停任务：启动、挂起与异常恢复

来源：17golang原创 2026-10-07 07:27:56 0浏览收藏

我第一次把 PHP Fiber 放进任务代码时，最麻烦的并不是 suspend() 本身，而是调用方很快散落了大量状态判断：第一次要用 start()，挂起后才能 resume()，异常要从挂起点注入，结束后又只能在正常返回时读取 getReturn()。把这些细节收进一个 PausableTask，业务层会清楚很多。

PHP Fiber 官方手册：https://www.php.net/manual/en/language.fibers.php

本文给出的最小配方是：由包装类持有一个 Fiber，外层只调用 start()、resume()、inject() 和 result()；任务内部用 Fiber::suspend() 交出控制权。可恢复异常在挂起点被捕获并转换为 recoverable 信号，调用方再决定重试还是终止。

先分清两组返回值

Fiber 的数据交换是双向的，这一点最容易绕晕。Fiber::suspend($out) 里的 $out 会返回给外层正在执行的 start()、resume() 或 throw()；下一次外层调用 resume($in) 时，$in 又会成为上一次 Fiber::suspend() 的返回值。

 'waiting']);

    // 中文说明：resume() 传入的值会从 suspend() 返回
    return 'processed:' . $payload;
});

$signal = $fiber->start();      // 中文说明：得到第一个挂起值
$fiber->resume('order-42');     // 中文说明：任务继续并正常返回
$result = $fiber->getReturn();  // 中文说明：只在正常终止后读取最终返回值

start() 只能用于尚未启动的 Fiber；resume() 和 throw() 要求 Fiber 正处于挂起状态。违反这些状态约束会得到 FiberError。这也是我更愿意提供包装类的原因：不让每个调用点重复记忆同一套前置条件。

最小封装：把状态判断收进 PausableTask

下面的包装类先解决三个问题：保存 Fiber、统一检查可调用状态、记录无法在任务内部恢复的异常。它没有实现事件循环，也没有偷偷启动线程，只是把协作式控制权交换变成稳定接口。

fiber = new Fiber(function () use ($work): mixed {
            while (true) {
                try {
                    // 中文说明：先报告可接收任务，再等待外层送入 payload
                    $payload = Fiber::suspend([
                        'state' => 'waiting',
                    ]);

                    return $work($payload);
                } catch (RecoverableTaskException $e) {
                    // 中文说明：把可恢复异常转换为状态信号，等待 retry 或 abort
                    $command = Fiber::suspend([
                        'state' => 'recoverable',
                        'message' => $e->getMessage(),
                    ]);

                    if ($command !== 'retry') {
                        throw $e;
                    }
                }
            }
        });
    }

    public function start(): array
    {
        if ($this->fiber->isStarted()) {
            throw new LogicException('任务已经启动');
        }

        return $this->capture(fn (): mixed => $this->fiber->start());
    }

    public function resume(mixed $value = null): array
    {
        $this->assertSuspended('恢复');
        return $this->capture(fn (): mixed => $this->fiber->resume($value));
    }

    public function inject(Throwable $exception): array
    {
        $this->assertSuspended('注入异常');
        return $this->capture(fn (): mixed => $this->fiber->throw($exception));
    }

    public function result(): mixed
    {
        if ($this->failure !== null) {
            // 中文说明：保留原异常，避免把失败伪装成正常返回
            throw $this->failure;
        }

        if (!$this->fiber->isTerminated()) {
            throw new LogicException('任务尚未结束');
        }

        return $this->fiber->getReturn();
    }

    public function isFinished(): bool
    {
        return $this->fiber->isTerminated();
    }

    private function assertSuspended(string $action): void
    {
        if (!$this->fiber->isSuspended()) {
            throw new LogicException("任务当前不能{$action}");
        }
    }

    private function capture(callable $operation): array
    {
        try {
            $signal = $operation();

            return [
                'state' => $this->fiber->isTerminated() ? 'done' : 'suspended',
                'signal' => $signal,
            ];
        } catch (Throwable $e) {
            // 中文说明：未被 Fiber 内部处理的异常从切换调用处冒出
            $this->failure = $e;
            return ['state' => 'failed', 'error' => $e];
        }
    }
}

这里的 capture() 很关键。官方文档说明，如果 Fiber 回调在挂起前或恢复后抛出未捕获异常，该异常会从 start()、resume() 或 throw() 冒出。包装类把它保存为失败状态，但不会吞掉原对象；调用 result() 时仍抛出同一个异常。

PausableTask、Fiber、启动恢复接口、挂起点、任务信号与返回值的静态封装关系 — 图1：PausableTask 封装结构图。外层只暴露启动、恢复和结果接口，Fiber 与挂起点留在任务边界内，TaskSignal 承担双向数据交换。此图为静态结构图，不是运行截图。

启动与恢复：让业务层只处理信号

包装后，调用方不再直接判断该用 start() 还是 resume()。首次启动得到 waiting 信号，再把任务数据送入挂起点：

 $payload['id'],
            'status' => 'completed',
        ];
    }
);

$startState = $task->start();
if (($startState['signal']['state'] ?? null) === 'waiting') {
    // 中文说明：只有看到 waiting 信号后才恢复 Fiber
    $task->resume(['id' => 42]);
}

$result = $task->result();

我比较喜欢让包装器返回结构化状态，而不是只返回 Fiber 的原始值。这样业务层能区分“刚挂起”“已经完成”和“未捕获失败”。代价是多了一层数组协议；规模较大的项目可以把它替换为只读 DTO 或枚举，减少字符串拼写错误。

把异常注入挂起点，并决定是否恢复

Fiber::throw($exception) 不是在 Fiber 外随便记录一个错误，而是恢复 Fiber，并让该异常从当前 Fiber::suspend() 调用处抛出。只有任务内部在对应边界捕获它，才有机会转成可恢复状态。

start();

// 中文说明：异常会从当前 suspend() 位置抛入 Fiber
$recoverable = $task->inject(
    new RecoverableTaskException('临时资源尚未准备好')
);

if (($recoverable['signal']['state'] ?? null) === 'recoverable') {
    // 中文说明：retry 让 Fiber 回到下一次 waiting 挂起点
    $waiting = $task->resume('retry');

    if (($waiting['signal']['state'] ?? null) === 'waiting') {
        $task->resume(['id' => 42]);
    }
}

$result = $task->result();

这个例子里的“恢复”包含两个决定。第一步，Fiber 内部只捕获 RecoverableTaskException，其他异常继续终止任务；第二步，调用方看到 recoverable 后明确发送 retry。如果传入其他命令，原异常重新抛出，包装器会记录为 failed。

这样做比无条件重试更稳妥：任务内部负责判断异常能否恢复，调度方负责判断当前是否应该重试。两者都不需要猜测对方的策略。

异常注入、Fiber throw、Throwable 捕获、可恢复信号、重试决策与任务结果的静态关系 — 图2：Fiber 异常恢复关系图。异常通过 Fiber::throw 注入当前挂起点，任务内部 catch 把可恢复状态转换为信号，外层再决定 retry 或结束。此图为静态关系图，不是运行证据。

三个容易踩到的状态坑

重复调用 start

一个 Fiber 只能启动一次。首次 start() 后，即使它马上挂起，再次调用 start() 也会触发 FiberError；继续执行应该改用 resume()。包装器用 isStarted() 提前把错误转换成更贴近业务的 LogicException。

在非挂起状态 resume 或 throw

未启动、正在运行或已经终止的 Fiber 都不能被恢复或注入异常。外层通常只会在 Fiber 把控制权交回来以后调用这些方法，因此 isSuspended() 是最直接的门禁。

失败终止后读取 getReturn

getReturn() 只返回 Fiber 回调正常返回的值。Fiber 尚未终止，或者因为未捕获异常而终止时，调用它都会得到 FiberError。包装类先检查保存的 $failure，再检查 isTerminated()，避免把两类状态混为一谈。

当前状态	允许的主要操作	应避免的操作
未启动	`start()`	`resume()`、`throw()`、`getReturn()`
已挂起	`resume()`、`throw()`	再次 `start()`
正常终止	`getReturn()`	继续恢复
异常终止	读取已保存异常	`getReturn()`