异常教程

PHP curl_multi_add_handle函数（长文讲解）

更新时间:

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

截止目前， 星球 内专栏累计输出 90w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 3100+ 小伙伴加入学习 ，欢迎点击围观

在现代 Web 开发中，高效处理多个 HTTP 请求是一个常见需求。无论是聚合多个 API 数据、并行下载文件，还是优化页面加载速度，多线程请求技术都能显著提升程序性能。PHP 的 cURL 库提供了 curl_multi_* 系列函数，其中 curl_multi_add_handle 函数是构建多线程请求的核心工具。本文将从零开始讲解这一函数的原理、用法及实战技巧，帮助开发者轻松掌握 PHP 多线程请求的实现方法。

一、多线程请求的基础概念

1. 什么是多线程请求？

多线程请求允许程序在同一时间发起多个 HTTP 请求，并通过事件驱动的方式管理这些请求的执行流程。这就像一家快递公司同时处理多个包裹：快递员（线程）可以分头行动，而非按顺序逐一处理。通过这种方式，程序的整体响应时间可缩短至最长单个请求的耗时，而非所有请求耗时之和。

2. PHP cURL 库的多线程支持

PHP 的 cURL 库通过 curl_multi_* 函数族实现了多线程请求功能。这些函数允许开发者将多个 cURL 句柄（即请求对象）整合到一个“队列”中，由 PHP 内部的事件循环统一管理。其中，curl_multi_add_handle 函数的作用是将单个 cURL 句柄添加到这个队列中，从而实现并发执行。

二、curl_multi_add_handle 函数详解

1. 函数语法与参数

bool curl_multi_add_handle(resource $multi_handle, resource $handle)
  • $multi_handle：由 curl_multi_init() 初始化的多线程句柄，代表整个请求队列。
  • $handle：通过 curl_init() 创建的单个 cURL 句柄，即需要添加到队列中的请求对象。

函数返回布尔值：true 表示添加成功，false 表示失败（通常因句柄无效或队列已关闭）。

2. 函数的核心作用

curl_multi_add_handle 将单个请求句柄加入多线程队列，但不会立即触发请求。实际执行需通过后续的 curl_multi_exec() 函数启动事件循环。这种设计类似“提交订单”与“开始配送”的分步操作，确保开发者能灵活控制请求流程。

三、使用 curl_multi_add_handle 的步骤解析

以下是使用 curl_multi_add_handle 构建多线程请求的完整流程：

1. 初始化多线程句柄

// 创建多线程句柄  
$mh = curl_multi_init();

curl_multi_init() 返回一个资源类型的句柄，用于管理后续添加的所有请求。

2. 创建并配置单个 cURL 句柄

// 创建第一个请求句柄  
$ch1 = curl_init();  
curl_setopt_array($ch1, [  
    CURLOPT_URL => 'https://api.example.com/data1',  
    CURLOPT_RETURNTRANSFER => true,  
]);  

// 创建第二个请求句柄  
$ch2 = curl_init();  
curl_setopt_array($ch2, [  
    CURLOPT_URL => 'https://api.example.com/data2',  
    CURLOPT_RETURNTRANSFER => true,  
]);

每个 cURL 句柄需单独初始化，并通过 curl_setopt() 或 curl_setopt_array() 配置请求参数。

3. 将句柄添加到多线程队列

// 将两个句柄添加到队列  
curl_multi_add_handle($mh, $ch1);  
curl_multi_add_handle($mh, $ch2);

此时，两个请求尚未实际发送，仅是“排队”状态。

4. 启动事件循环并执行请求

// 执行多线程请求  
$running = null;  
do {  
    $mrc = curl_multi_exec($mh, $running);  
} while ($mrc == CURLM_CALL_MULTI_PERFORM && $running > 0);  

// 处理等待时间（非阻塞方式）  
while ($running && $mrc == CURLM_OK) {  
    $mrc = curl_multi_exec($mh, $running);  
    if ($running > 0) {  
        curl_multi_select($mh, 1); // 等待 1 秒，避免 CPU 占用过高  
    }  
}

curl_multi_exec() 是多线程请求的“引擎”，它启动事件循环并处理所有请求。通过 curl_multi_select() 可以控制等待超时时间，避免无限循环。

5. 获取响应结果并清理资源

// 获取每个请求的结果  
$results = [];  
foreach ([$ch1, $ch2] as $ch) {  
    $results[] = [  
        'content' => curl_multi_getcontent($ch),  
        'info' => curl_getinfo($ch),  
    ];  
    curl_close($ch); // 关闭单个句柄  
}  

// 关闭多线程句柄  
curl_multi_close($mh);

通过 curl_multi_getcontent() 可获取响应内容，curl_getinfo() 提供请求的详细信息（如 HTTP 状态码、响应时间等）。最后需关闭所有资源以释放内存。

四、实战案例：并行请求多个 API

假设我们需要同时请求三个天气 API，聚合结果后输出。以下是完整代码示例：

// 初始化多线程句柄  
$mh = curl_multi_init();  

// 创建三个请求句柄  
$urls = [  
    'https://api.weather.com/region1',  
    'https://api.weather.com/region2',  
    'https://api.weather.com/region3',  
];  

// 循环创建并添加句柄  
foreach ($urls as $url) {  
    $ch = curl_init();  
    curl_setopt_array($ch, [  
        CURLOPT_URL => $url,  
        CURLOPT_RETURNTRANSFER => true,  
        CURLOPT_TIMEOUT => 5, // 设置超时时间为 5 秒  
    ]);  
    curl_multi_add_handle($mh, $ch);  
}  

// 执行多线程请求  
$running = null;  
do {  
    $mrc = curl_multi_exec($mh, $running);  
} while ($mrc == CURLM_CALL_MULTI_PERFORM);  

while ($running && $mrc == CURLM_OK) {  
    $mrc = curl_multi_exec($mh, $running);  
    if ($running > 0) {  
        curl_multi_select($mh, 0.1); // 短暂等待，避免高 CPU 占用  
    }  
}  

// 收集结果  
$results = [];  
$active = null;  
curl_multi_info_read($mh, $active); // 清空缓冲  

foreach ($urls as $index => $url) {  
    $ch = $mh->handles[$index]; // 获取句柄（需注意句柄顺序可能变化）  
    $results[$url] = [  
        'content' => curl_multi_getcontent($ch),  
        'http_code' => curl_getinfo($ch, CURLINFO_HTTP_CODE),  
    ];  
    curl_close($ch);  
}  

// 输出结果  
echo "请求结果：\n";  
foreach ($results as $url => $data) {  
    echo "URL: $url\n";  
    echo "HTTP 状态码: " . $data['http_code'] . "\n";  
    echo "内容:\n" . $data['content'] . "\n";  
}  

// 关闭多线程句柄  
curl_multi_close($mh);

案例解析

  1. 动态添加句柄：通过循环遍历 URL 列表，动态创建并添加多个请求，避免重复代码。
  2. 错误处理：设置 CURLOPT_TIMEOUT 防止请求无限等待，curl_multi_info_read() 检查是否有错误发生。
  3. 结果收集：通过句柄索引关联 URL 和响应数据，确保结果与请求一一对应。

五、关键注意事项与优化建议

1. 常见错误及解决方法

  • 未初始化多线程句柄：
    若忘记调用 curl_multi_init()，curl_multi_add_handle 会返回 false。
  • 句柄未关闭：
    未调用 curl_close() 或 curl_multi_close() 会导致内存泄漏。
  • 超时未处理：
    长时间无响应的请求可能阻塞整个队列，需合理设置 CURLOPT_TIMEOUT 和 curl_multi_select() 的超时时间。

2. 性能优化技巧

  • 控制并发数量：
    过多的并发请求可能因服务器限制或网络拥堵导致失败，建议通过 curl_multi_select() 的超时参数或队列大小动态调整。
  • 错误重试机制：
    对返回 HTTP 5xx 状态码的请求，可加入重试逻辑（例如使用 curl_multi_strerror() 检查错误码）。
  • 异步非阻塞模式：
    在高并发场景中，可结合 curl_multi_exec() 的非阻塞特性，将长时间任务移至后台处理。

六、对比单线程与多线程的性能差异

以下表格对比了单线程与多线程请求的执行时间（假设每个请求耗时 2 秒）：

请求数量单线程总耗时多线程总耗时性能提升倍数
12 秒2 秒1 倍
24 秒2 秒2 倍
510 秒2 秒5 倍

表格说明：多线程请求的总耗时接近单个请求的最大耗时，而非所有请求耗时之和。因此，随着请求数量增加，性能提升越显著。

结论

curl_multi_add_handle 函数是 PHP 实现高效多线程请求的核心工具。通过合理配置和管理 cURL 句柄，开发者可以显著提升程序的吞吐量和响应速度。无论是聚合多个 API 数据、批量下载资源，还是优化 Web 应用的性能，掌握这一技术都能带来实际价值。

在使用过程中，需注意资源管理和错误处理，避免因并发数过高或网络波动导致程序崩溃。未来，随着异步编程和协程技术的普及，多线程请求的实现方式将进一步多样化，但 curl_multi_add_handle 仍会是传统同步场景下的重要选择。

希望本文能帮助开发者快速上手 PHP 多线程请求，并在实际项目中灵活应用这一技术。

最新发布

查看更多文章