Hyperf如何优雅处理第三方API请求限流_使用GuzzleRetry中间件-php教程-PHP中文网

guzzle 默认 retry 不处理 429，因 decider 未包含该状态码；需自定义 decider 判断 429，并在 delay 中解析 retry-after（支持秒数或 http-date），结合指数退避实现优雅限流重试。

hyperf如何优雅处理第三方api请求限流_使用guzzleretry中间件

Hyperf 里用 Guzzle 做第三方 API 调用时，光配 retry 中间件不够——它只管失败重试，不管限流触发后的等待与节流。真正的“优雅”，是让请求在被服务端返回 429 Too Many Requests 后，自动解析 Retry-After 头、或按指数退避延迟重试，而不是无脑冲。

为什么 Guzzle 的默认 retry 不处理 429？

Guzzle 的 RetryMiddleware 默认只对网络异常（如 ConnectException）和 5xx 响应重试，429 被当成“合法失败响应”直接透出，不会进重试逻辑。你看到的请求瞬间失败、没延迟、没退避，就是这个原因。

检查源码可知：RetryMiddleware 的默认 decider 函数不包含对 429 状态码的判断
httpErrors 中间件若启用，会提前把 429 转成异常，但 RetryMiddleware 默认也不重试这类异常（除非你显式配置）
即使手动加了 429 判断，Guzzle 本身不解析 Retry-After，得自己从响应头读取并转成毫秒延迟

如何让 retry 中间件识别 429 并动态延迟？

你需要自定义 decider 和 delay 函数，并确保它们能访问到响应对象（或异常里的响应）。

Hyperframes Creative

HyperFrames视频非动画创意指导，包括设计规范（frame.md/design.md）处理、配色、字体设计、旁白及节奏规划等。

下载

用 Middleware::retry() 创建中间件时，传入闭包形式的 decider：检测 $reason 是否为 RequestException，再判断 $reason->getResponse()->getStatusCode() === 429
delay 函数不能只写 exponentialDelay；要优先读 $reason->getResponse()->getHeaderLine('Retry-After')，若存在且为数字，直接返回 (int)$header * 1000；否则 fallback 到指数退避
注意：Hyperf 的 GuzzleClient 实例通常由 Factory 创建，中间件需注入到 HandlerStack，而非仅传给单次 request()

示例关键片段：

$decider = function ($retries, $request, $response, $exception) {
    if ($exception instanceof RequestException && $exception->getResponse()) {
        return $exception->getResponse()->getStatusCode() === 429;
    }
    return $retries getStatusCode() >= 500);
};
<p>$delay = function ($retries, $request, $response, $exception) {
if ($exception instanceof RequestException && $exception->getResponse()) {
$retryAfter = $exception->getResponse()->getHeaderLine('Retry-After');
if (is_numeric($retryAfter)) {
return (int)$retryAfter <em> 1000;
}
}
return (int)pow(2, $retries - 1) </em> 1000;
};</p><p>$stack = HandlerStack::create();
$stack->push(Middleware::retry($decider, $delay));
</p>

Hyperf 下如何复用 Guzzle 配置并避免中间件污染？

Hyperf 的 Guzzle 客户端支持通过 config/autoload/guzzle.php 全局配置 handler，但直接改这个文件会让所有 Guzzle 实例共用同一套限流逻辑——这在多租户或对接多个第三方 API 时很危险。

推荐做法：为不同 API 创建独立的 ClientFactory，每个 factory 返回带专属 HandlerStack 的 client
不要在 guzzle.php 里硬编码 RetryMiddleware，而是用 DI 注入方式，在需要的地方按需构造带限流的 client
如果用了 hamburgscleanest/guzzle-advanced-throttle 这类高级限流包，它的 ThrottleMiddleware 本身已内置 429 处理，但要注意它和 RetryMiddleware 的执行顺序——ThrottleMiddleware 应放在更外层，先做主动限速；RetryMiddleware 放内层，专做兜底重试