PHP Symfony HttpClient 怎样设置连接和响应超时

Symfony HttpClient 的超时不要只盯着一个数字：连接建立、响应过程中的空闲间隔、整次请求的最大耗时，解决的是三种不同的等待问题。最小可用的组合通常是把 max_connect_duration 设得更短，用 timeout 限制“长时间没有任何响应数据”，再用 max_duration 给完整请求设总预算。

官方地址：https://symfony.com/doc/current/http_client.html

如果只想防止连接阶段卡住，优先看 max_connect_duration；如果担心响应中途停顿，配置 timeout；如果必须让整次调用在固定时间内结束，再加 max_duration。

三个超时参数分别管什么

Symfony 文档把 timeout 定义为请求保持活跃前允许的空闲时间。DNS、TCP 建连、TLS 握手或响应内容长时间没有进展，都可能触发这个预算。它不是“从发起请求开始的总秒数”：只要响应持续有数据，较大的响应可以超过这个时间。

max_duration 才是完整请求和响应的总时长上限；max_connect_duration 用于单独限制 DNS、TCP 和 TLS 建立连接的阶段，Symfony 官方文档标注该选项从 8.1 引入。

先写一组有明确预算的请求

下面的配置让连接阶段最多等待 0.5 秒；连接建立后，如果 10 秒内没有新的响应进展就认为空闲超时；无论服务是否持续返回数据，整次调用最多持续 15 秒。

request('GET', 'https://api.example.com/report', [
        'max_connect_duration' => 0.5,
        // 响应长时间没有新数据时触发，而不是限制总字节数。
        'timeout' => 10,
        // 给整个请求/响应设置绝对上限，避免持续小片段数据拖太久。
        'max_duration' => 15,
    ]);

    // 响应是懒加载的，读取状态码或正文时仍可能发生网络异常。
    $status = $response->getStatusCode();
    $data = $response->toArray();
} catch (TransportExceptionInterface $e) {
    // 统一处理连接失败、空闲超时和读取阶段的传输异常。
    $status = 0;
    $data = ['error' => $e->getMessage()];
}

这组参数的关键不是“越小越好”，而是让三种预算各自对应一个可解释的业务边界。连接预算适合快速失败，空闲预算适合发现服务端停止输出，总预算适合保护队列消费者、控制器或命令行任务的最长占用时间。

为什么异常要包住响应读取

Symfony HttpClient 返回的是惰性响应对象。调用 request() 时不一定已经完成 DNS、建连、接收响应头和读取正文，因此只在 request() 外层捕获异常并不完整。getStatusCode()、getHeaders()、getContent()、toArray() 等方法都可能把后续网络操作推进到真正发生。

因此，业务层更适合把“创建响应对象”和“读取响应内容”放进同一个 try 块。若只需要流式处理，可以使用 stream()，并在遍历时检查 chunk 的状态；这时要把流式读取的空闲判断与单次请求的 timeout 区分开。

适合放在哪一层，哪些写法容易失效

同一套外部 API 如果由多个服务调用，可以在 scoped client 中设置共同的默认值，再在特殊请求上覆盖。单次请求参数优先表达局部例外，例如导出接口允许更大的总预算，但不应顺手把所有连接预算都放大。

# config/packages/framework.yaml
framework:
    http_client:
        scoped_clients:
            report.client:
                base_uri: 'https://api.example.com/'
                # 共享客户端的默认空闲和总时长预算。
                timeout: 10
                max_duration: 15
                # Symfony 8.1 及以上可单独限制建连阶段。
                max_connect_duration: 0.5

常见误区有三个：把 timeout 当成绝对总时长；只捕获 request() 不捕获响应读取；以及在 Symfony 版本或底层客户端不支持时直接使用 max_connect_duration。最后一种情况应先确认项目依赖版本，并根据文档选择兼容配置。

一张表决定该调哪个参数

把这张表和业务 SLA 放在一起看，就能避免遇到一次慢请求便盲目增大所有超时。对大响应或流式接口，合理的空闲预算可以比总预算更宽松；对短接口，则可以让连接预算和总预算更紧凑。

相关问题

timeout 能限制完整响应的总时间吗？

不能。它主要限制请求保持活跃期间的空闲时间。要限制完整请求/响应持续多久，应使用 max_duration。

max_connect_duration 设置为 0 会怎样？

官方契约把小于等于 0 解释为不单独限制建连阶段，但仍受 timeout 约束。生产配置应避免依赖无限等待，最好结合调用链的总预算明确设置。

为什么 getContent 才抛出超时异常？

因为响应采用懒加载，网络工作可能延迟到读取状态码、正文或转换 JSON 时才推进。异常处理应覆盖这些调用。

总结一下：连接慢看 max_connect_duration，中途没进展看 timeout，整体超时看 max_duration；并且要把整个响应读取链路放在 TransportExceptionInterface 的处理范围内。