Hyperf 3.1 中需在单次请求内并发调用多个第三方 API，必须使用 Hyperf\HttpClient\Client 并通过 parallel 函数或手动协程+Channel 实现非阻塞并发，严禁使用 Guzzle 同步客户端，且所有操作须在协程上下文（如 Controller 方法）中执行，否则会挂起调度器。
Hyperf 3.1 中需在单次请求内并发调用多个第三方 API（如支付验签、用户资料、风控查询），既要保证协程不阻塞，又要避免超时或连接耗尽，不能靠 sleep 或串行等待。
确认协程环境已就绪
在控制器或服务方法中，先验证当前上下文是否处于协程中：执行 Co::getuid()，若返回非 null 整数，则说明已在协程内；若抛出 Co::getuid() must be called in coroutine 异常，说明代码未被协程调度器包裹——常见于在 __construct 或命令行非 runBlocking 环境中调用。
【必须在 onRequest 或协程生命周期内调用】 所有并发逻辑只能在 Swoole 的 onRequest 回调、Hyperf 的 @Controller 方法、或 go/parallel 启动的协程中执行。
使用 parallel 并发发起 HTTP 请求
Hyperf 3.1 内置 Hyperf\Coroutine\parallel 函数，底层基于 Co::create + Channel 协调，是并发调用第三方 API 的首选方式。
方法一：直接传入匿名函数数组
定义三个闭包，分别调用不同 API，每个闭包内部使用 Hyperf\HttpClient\Client 实例发起请求：
$result = parallel([
function () use ($client) { return $client->get('https://api.a.com/check?order=123'); },
function () use ($client) { return $client->get('https://api.b.com/profile?id=456'); },
function () use ($client) { return $client->post('https://api.c.com/risk', ['body' => ['user_id' => 789]]); },
]);
这一步会并发执行全部请求，$result 是包含三个 Response 对象的数组，顺序与传入函数一致。
方法二：带超时控制的 parallel
为防止某个接口异常慢拖垮整体，必须显式设置超时：
$result = parallel([/* 同上 */], 3.0); // 第二个参数为总超时秒数，单位秒
若任一协程超过 3 秒未返回，整个 parallel 调用抛出 Hyperf\Coroutine\Exception\ParallelTimeoutException，不会卡住后续逻辑。
手动管理协程并处理失败重试
当需要对特定接口做差异化重试策略（如风控接口失败后重试 1 次，资料接口只试 1 次），就不能依赖 parallel 的统一超时，而要手动启协程 + Channel 收集结果。
第一步：创建带缓冲的 Channel，容量设为请求数量
$chan = new Channel(3);
第二步：为每个请求启动独立协程，成功/失败都向 channel 发送结构化结果
go(function () use ($client, $chan) {
try {
$resp = $client->get('https://api.a.com/check')->getBody()->getContents();
$chan->push(['status' => 'success', 'data' => json_decode($resp, true)]);
} catch (Throwable $e) {
$chan->push(['status' => 'fail', 'error' => $e->getMessage()]);
}
});
第三步：循环接收，最多等 4 秒，避免无限挂起
$results = [];
for ($i = 0; $i
$res = $chan->pop(4.0); // 每次 pop 最多等 4 秒
if ($res === null) {
$results[] = ['status' => 'timeout'];
} else {
$results[] = $res;
}
}
第四步：检查结果，对 status 为 fail 的条目按需重试（例如风控接口 code == 503 时重试一次）
if ($results[2]['status'] === 'fail' && str_contains($results[2]['error'], '503')) {
// 构造新协程重试，不再 push 到原 channel，而是单独处理
go(function () use ($client) {
// 重试逻辑
});
}
禁用 Guzzle，必须用 Hyperf\HttpClient\Client
Hyperf 3.1 默认禁用 Guzzle 同步客户端。若项目中残留 new \GuzzleHttp\Client()，会导致整个协程调度器挂起——所有其他协程停止执行，QPS 归零。
正确做法是注入或获取 Hyperf\HttpClient\Client 实例：
$client = ApplicationContext::getContainer()->get(\Hyperf\HttpClient\Client::class);
该 Client 底层使用 Swoole\Coroutine\Http\Client，天然支持协程切换，且自动复用连接、支持 keep-alive。
注意：不要在构造函数中调用 $client->get() ——构造函数不在协程上下文中，会直接报错。
