PHP generators 怎样用 return value 传递最终结果

我第一次把 PHP generator 用在批量读取任务时，最容易混淆的是：yield 给调用方的是“过程中的一项”，而 return 给调用方的是“生成器已经结束后的最终结果”。如果想边遍历边拿到记录，同时在最后取得处理数量、摘要或状态，就让生成器用 yield 输出数据，再在结尾 return 一个值，遍历完成后调用 Generator::getReturn()。

我为什么把流式数据和最终摘要拆成两条通道

在小数据量场景里，把所有记录收集成数组再返回很直观，但批量导入、逐行解析或长列表处理时，调用方往往希望“拿到一项就处理一项”，而不是等待整个数组构造完成。生成器正好把这一段过程拆开：每次 yield 暂停并交出一项，调用方继续迭代时再恢复生成器。

PHP 官方手册把生成器的最终返回值定义为可通过 Generator::getReturn() 取得的值。对我来说，最稳定的设计是把记录、统计和完成状态分开：记录走 yield，统计摘要走 return。这样调用方不用猜最后一条 yielded 数据是不是“特殊的汇总项”。

在生成器结尾返回累计数量和处理摘要

下面的例子模拟逐项读取订单编号。它没有把全部订单先装进数组，而是每次产出一个编号，同时在生成器结束处返回统计信息。代码中的中文注释只解释关键边界，便于后面把示例替换成文件读取或数据库游标。

 $processed,
        'status' => 'completed',
    ];
}

$generator = streamOrderIds([
    ['id' => 101],
    ['id' => 102],
]);

foreach ($generator as $orderId) {
    // 这里可以把当前编号写入队列或交给下一层处理。
    echo $orderId, PHP_EOL;
}

// foreach 返回后，生成器已经结束，此时才能读取 return value。
$summary = $generator->getReturn();
echo $summary['processed'], PHP_EOL;

这里的关键不是把 return 写在函数底部，而是调用时机：只有遍历已经推动生成器走过最后一个 yield，生成器才有“最终结果”。getReturn() 读取的是这个返回值，不会重新执行生成器，也不会从 yielded 数据里寻找最后一项。

从规模化处理角度看，getReturn() 的位置决定了接口是否可靠

把生成器当成一条小型数据管道时，调用方通常有三个边界：生成器对象刚创建、正在输出数据、已经自然结束。只有第三个边界允许读取最终返回值。刚创建时调用 getReturn()，生成器还没有结束；遍历中途因为提前 break，也不能把返回摘要当成完整统计。

如果业务允许提前停止，建议在调用方明确记录“未完成”，不要把未取得的 return value 当成成功摘要：

= 100) {
        // 提前停止意味着生成器可能尚未自然结束，不能调用 getReturn()。
        break;
    }
}

// 提前停止时，使用调用方自己的状态表达“未完成”。
$result = [
    'status' => 'stopped_early',
    'seen' => $seen,
];

这也是我在长批次任务里比较看重的取舍：getReturn() 很适合表达“完成后才成立”的摘要，但它不是一个随时可查询的进度接口。需要实时进度时，应该单独设计计数器、回调或外部状态，而不是反复尝试读取生成器的最终返回值。

无返回值、未完成和异常分别怎么处理

这个 API 有三个容易被忽略的边界。第一，生成器没有显式 return 也可以自然结束，此时最终值相当于 null。第二，生成器尚未结束时调用 getReturn()，不能当成“暂时返回空值”处理，而要先推动它完成，或改变调用流程。第三，如果生成器内部抛出异常，遍历会中断，正常的最终摘要也不会替代这个异常。

因此，调用方最好把遍历和读取最终值放在同一个 try 中，并只在遍历完整返回后使用摘要：

getReturn();
} catch (Throwable $exception) {
    // 异常路径保留真实失败原因，不读取或拼接一个假的最终结果。
    $summary = [
        'status' => 'failed',
        'message' => $exception->getMessage(),
    ];
}

如果你只需要逐项消费，不需要最终摘要，就不必为了“完整”而添加 return。如果确实要返回统计信息，则让返回结构保持稳定，例如固定使用 processed 和 status 字段，避免调用方一会儿拿整数、一会儿拿数组。

常见问题

return value 会不会被 foreach 当成最后一项？

不会。foreach 只消费 yield 产生的迭代值；return 的值要在生成器结束后通过 getReturn() 单独取得。

为什么刚创建 Generator 就调用 getReturn() 会失败？

因为生成器函数调用时通常只创建了 Generator 对象，函数体还没有走到结束。先完整遍历，或明确推动它自然结束，再读取最终值。

提前 break 后能不能强行读取最终统计？

不能把它当作完整统计。提前停止表示生成器可能没有执行完，应该在调用方记录 stopped_early，或者设计专门的取消与收尾协议。

参考资料：PHP 官方 https://www.php.net/manual/en/generator.getreturn.php、https://www.php.net/manual/en/generators.syntax.php。