PHP 如何用 Fiber 拆分长任务：挂起、恢复与返回值边界

处理批量导入、分段计算这类长任务时，PHP 代码最怕把所有工作塞进一次请求：中途既不能让出执行权，也很难在外层知道任务停在哪里。Fiber 可以把调用栈完整地暂停下来，等外层再次恢复；但它不是线程，真正的并发调度仍然需要事件循环或调用方自己安排。

先记住这条边界：Fiber::start 负责第一次进入，Fiber::suspend 把值交回外层，Fiber::resume 把值送回暂停点，只有 Fiber 结束后才能用 Fiber::getReturn 读取最终返回值。

先把一次长任务拆成两个可验收的阶段

下面的例子模拟导入任务：第一段处理批次，遇到检查点就暂停；外层拿到检查点后做记录，再恢复任务。示例把节点故意压缩到最少，方便看清调用顺序。

start();
echo $paused, PHP_EOL;

$fiber->resume('checkpoint-accepted');
echo $fiber->getReturn(), PHP_EOL;

第一次 start() 执行到 Fiber::suspend 就返回 batch-1-ready，闭包没有继续向下执行。第二次 resume() 让暂停点得到 checkpoint-accepted，闭包随后返回字符串，Fiber 才进入终止状态。

暂停值不是任务结果，getReturn 也不能提前读

Fiber::suspend 的参数是给外层的阶段信号，resume 的参数则会成为暂停点的返回值。两边可以是不同类型，也不要求等于最终结果。

因此下面的核对顺序很重要：

1. 调用 Fiber::start，确认返回的是本阶段信号。
2. 调用 Fiber::isSuspended，确认任务确实停在暂停点。
3. 调用 Fiber::resume，把外部确认值送回任务。
4. 调用 Fiber::isTerminated 后，再调用 Fiber::getReturn 读取最终结果。

如果在第三步之前读取 getReturn，PHP 会抛出 FiberError；如果闭包是以异常结束，也不能把它当成正常返回值读取。

把恢复逻辑放进一个小型调度循环

单个 Fiber 的价值不在于自动并发，而在于把“任务暂停”和“何时继续”拆开。多个任务时，外层可以保存 Fiber 对象，轮询 isSuspended，并根据外部 I/O 或队列结果逐个调用 resume。

while (!$fiber->isTerminated()) {
    if ($fiber->isSuspended()) {
        $fiber->resume('next-checkpoint');
    }
}

$result = $fiber->getReturn();

这个循环只是演示调度边界，不会让阻塞式数据库查询凭空变成异步操作。真正接入 Web 请求时，还要为超时、客户端断开和异常恢复设计退出路径。

Fiber、Generator 和直接调用怎么选

任务本身很短、没有外部等待时，直接调用最简单；需要把暂停点暴露给调用方时，Fiber 更贴近“暂停完整调用栈”的需求；如果你要的是逐项产出数据流，Generator 的 yield 通常更自然。Fiber 不会替你提供线程，也不会替你安排多个任务的公平调度。

• 选择直接调用：一次函数调用可以在当前请求内完成。
• 选择 Fiber：需要暂停深层调用，并由外层决定何时恢复。
• 选择 Generator：调用方主要消费一系列逐项产出的值。

上线前检查这几个容易混淆的边界

第一，恢复一个已经终止的 Fiber 没有意义；第二，Fiber::suspend 必须在 Fiber 执行上下文中调用；第三，异常应该由调用方决定是记录、重试还是终止任务，而不是把异常对象误当成业务结果。把状态判断和结果读取写在同一处，排错会比散落在多个回调里容易。

相关问题

Fiber 能代替 PHP 多线程吗？

不能。Fiber 是同一 PHP 执行环境中的可中断调用栈，调度和真正的非阻塞 I/O 需要外围机制配合。

为什么 suspend 的值和 getReturn 的值不同？

前者是阶段信号，后者是闭包正常结束时的最终返回值，它们分别对应暂停和终止两个时刻。

小结

把 Fiber 当成一条清晰的控制流：Fiber::start 进入任务，Fiber::suspend 交出阶段值，Fiber::resume 恢复暂停点，任务终止后才由 Fiber::getReturn 取回结果。先把状态边界写清楚，再考虑如何接入调度器，代码会更稳。