PHP Fiber getReturn 怎样读取协程最终返回值

PHP 8.1 及以上可以用 Fiber 表示可暂停、可恢复的调用栈。读取协程最终返回值时，关键方法是 Fiber::getReturn()，但它不是 start()、Fiber::suspend() 或 resume() 的替代品：只有 Fiber 已经正常终止，才能读取回调最后的 return。

官方资料：https://www.php.net/manual/en/fiber.getreturn.php

直接结论：先让 Fiber 完成，再调用 isTerminated() 判断状态，最后用 getReturn() 取最终值。未启动、仍挂起或抛出异常时直接读取，会得到 FiberError。

Fiber 的几种返回值要分开看

Fiber 里至少有四种容易混淆的值：start() 可能拿到第一次挂起值，Fiber::suspend() 把值交给外部，resume() 把值送回 Fiber，而回调中的 return 才是最终结果。getReturn() 读取的是最后一种。

例如下面的写法中，start() 先得到暂停时的字符串；恢复后，回调才继续执行并返回数组。最终数组要通过 getReturn() 读取。

 $resumeValue, 'status' => 'done'];
});

// start() 得到的是 suspend() 的值，不是回调最后的 return。
$suspendedValue = $fiber->start();

// resume() 的参数会回到 Fiber::suspend() 表达式中。
$fiber->resume('ready');

// 只有回调正常结束后，getReturn() 才能读取最终数组。
$finalValue = $fiber->getReturn();

从旧的直接读取改成终止后读取

迁移旧代码时，最常见的问题是把“已经调用过 start()”误认为“已经有最终结果”。实际上，Fiber 可能还处于 suspended 状态；此时最终 return 尚未发生。

因此，旧的“启动后立即取结果”逻辑应改成：由调度代码负责继续恢复 Fiber，完成后再统一读取最终结果。

getReturn 的调用条件和异常边界

官方手册明确指出，Fiber 未启动、尚未终止，或者回调抛出异常而没有返回值时，调用 getReturn() 会抛出 FiberError。这不是返回 null 的另一种写法，调用方需要显式处理生命周期。

isTerminated()) {
    try {
        $result = $fiber->getReturn();
    } catch (FiberError $error) {
        // 记录生命周期错误，交给上层决定是否重试或降级。
        $result = null;
    }
} else {
    // suspended 或未启动都表示最终 return 尚未可读。
    $result = null;
}

如果回调本身抛出业务异常，应在恢复 Fiber 的位置捕获原异常；不要只依赖 getReturn() 来判断失败。FiberError 更适合表示调用时机不正确，例如 Fiber 尚未完成就读取结果。

PHP 8.1+ 迁移清单

1. 确认运行环境支持 Fiber，最低语言版本是 PHP 8.1。
2. 把 start() 和 resume() 的返回值标记为挂起交互值，不再命名为最终结果。
3. 在集中收口的位置检查 isTerminated()，再调用 getReturn()。
4. 为未启动、仍挂起、异常退出三种状态分别设计日志或降级策略。
5. 检查回调的返回类型，避免最终数组、对象和标量在上层被错误转换。

一句话记忆：suspend() 负责把 Fiber 暂停给外部，resume() 负责把值送回 Fiber，return 负责结束回调，getReturn() 只负责在结束后取回这个最终值。

常见问题

Fiber::getReturn() 可以在 start() 后立刻调用吗？

只有 Fiber 已经在没有挂起点的情况下直接结束时才可以。只要回调仍 suspended，就应先继续 resume，等 isTerminated() 为真后再读。

Fiber 没有显式 return 时会怎样？

回调没有返回值时，正常终止和“尚未终止”仍要区分。调用方应先确认生命周期，再根据业务约定处理最终值；不要用一次 getReturn() 调用同时判断状态和结果。