科技行业

如何在 PHP 中处理 API 超时、速率限制和重试

How to Handle API Timeouts, Rate Limits, and Retries in PHP

学习如何使用连接超时、HTTP 错误处理、指数退避、Retry-After 支持以及安全重试策略,构建可靠的 PHP API 集成

API 集成在开发期间运行完美。然后,有一天,你的定时任务中途停止。远程服务返回 HTTP 429,连接超时,或者 HTTP 503 错误中断了同步。

人们很容易想立即重试请求。

但没有策略地重试可能会让问题更糟。它可能使本已吃力的 API 过载、超出速率限制,或意外创建重复的订单和支付。

可靠的 API 客户端需要的不仅仅是一次成功的 curl_exec() 调用。

在本教程中,我们将构建一个实用的 PHP HTTP 客户端,用于处理连接超时、HTTP 错误、速率限制和临时失败。我们还会解释何时重试是安全的、何时不安全,以及如何在生产环境中诊断问题。

这些示例使用 PHP 内置的 cURL 扩展,不依赖 Composer 或第三方依赖。

1. 理解不同类型的 API 失败

并非每个不成功的请求都应采用相同方式处理。

失败 典型原因 建议操作
连接超时 服务器不可达或连接缓慢 谨慎重试
HTTP 400 请求参数无效 修正请求
HTTP 401 凭据无效或已过期 检查身份验证
HTTP 404 资源未找到 检查资源标识符
HTTP 429 超出 API 速率限制 遵守 Retry-After
HTTP 500 内部服务器错误 有选择地重试
HTTP 503 临时服务不可用 延迟后重试
无效 JSON 意外的响应格式 记录并调查

网络错误也与 HTTP 错误不同。

当 API 返回 HTTP 500 时,HTTP 请求已完成,服务器返回了错误响应。

当 cURL 报告连接失败时,你的应用可能根本没有收到任何 HTTP 响应。

在决定是否重试时,这种区别很重要。

2. 始终配置连接和请求超时

PHP cURL 提供了两个特别有用的设置:

CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,

CURLOPT_CONNECTTIMEOUT 限制连接阶段,而 CURLOPT_TIMEOUT 限制整个传输持续时间。两者都在 PHP 官方 cURL 参考文档中有说明。

如果没有适当的限制,缓慢的外部服务可能会让 PHP 工作进程被占用远超预期的时间。

对于常规 JSON API,一个实用的起点可能是连接建立用五秒,完整请求用十五秒。

这些并非通用值。文件上传或长时间运行的报告生成可能需要不同的超时策略。

发起你的第一个 API 请求

<?php
declare(strict_types=1);

$url = 'https://api.example.com/products';

$curl = curl_init($url);

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_FOLLOWLOCATION => false,
]);

$response = curl_exec($curl);
$statusCode = curl_getinfo(
    $curl,
    CURLINFO_HTTP_CODE
);

if ($response === false) {
    $error = curl_error($curl);

    curl_close($curl);

    throw new RuntimeException(
        'API request failed: ' . $error
    );
}

curl_close($curl);

echo 'HTTP status: ' . $statusCode;

这建立了一个有用的基础,但它尚未处理速率限制或可重试的失败。

3. 理解 HTTP 429 和 Retry-After

HTTP 429 表示客户端在 API 提供方定义的时间段内发送了过多请求。

有些 API 会按分钟、按小时、按 API 密钥或按账户施加限制。

服务器可能返回:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

Retry-After 请求头告诉客户端在再次尝试之前应等待多久。

该请求头可以包含秒数或 HTTP 日期。

例如:

Retry-After: 120

或者:

Retry-After: Wed, 25 Nov 2026 10:00:00 GMT

行为良好的客户端应遵守此指令,而不是反复发送请求。

如果服务器未提供重试延迟,你的应用需要一种回退策略。

4. 使用指数退避而不是立即重试

指数退避会在连续失败后增加等待时间。

例如:

重试 示例延迟
1 1 秒
2 2 秒
3 4 秒
4 8 秒

应用不是每秒重试一次,而是逐步等待更长时间。

添加一种称为抖动的微小随机变化,有助于防止许多客户端同时重试。

下面是一个可复用的延迟函数:

<?php
declare(strict_types=1);

function getRetryDelayMs(int $attempt): int
{
    $baseDelay = 1000;
    $maximumDelay = 30000;

    $exponentialDelay = min(
        $maximumDelay,
        $baseDelay * (2 ** ($attempt - 1))
    );

    return random_int(
        0,
        (int)$exponentialDelay
    );
}

这里使用完全抖动:实际延迟在零和指数上限之间随机选择。

随机延迟减少了同步的重试突发,尽管它不能替代明确的、由服务器提供的 Retry-After 指令。

Illustration of the article's main concept

5. 构建一个可复用的 PHP API 客户端

让我们把前面的概念组合成一个可工作的实现。

我们的客户端将:

  • 设置连接和整体请求超时。
  • 返回 HTTP 状态和响应体。
  • 检测传输失败。
  • 重试选定的临时失败。
  • 存在时遵守 Retry-After。
  • 限制尝试次数。
  • 避免自动重试非幂等操作。
<?php
declare(strict_types=1);

/**
 * Perform an HTTP GET request with bounded retries.
 *
 * Use only with trusted, configured API URLs.
 */
function apiGet(
    string $url,
    int $maxAttempts = 3
): array {
    if ($maxAttempts < 1) {
        throw new InvalidArgumentException(
            'maxAttempts must be at least 1.'
        );
    }

    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        $headers = [];

        $curl = curl_init($url);

        if ($curl === false) {
            throw new RuntimeException(
                'Unable to initialize cURL.'
            );
        }

        curl_setopt_array($curl, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CONNECTTIMEOUT => 5,
            CURLOPT_TIMEOUT => 15,
            CURLOPT_FOLLOWLOCATION => false,
            CURLOPT_HTTPGET => true,
            CURLOPT_HEADERFUNCTION => static function (
                $curl,
                string $headerLine
            ) use (&$headers): int {
                $length = strlen($headerLine);

                if (str_starts_with(
                    $headerLine,
                    'HTTP/'
                )) {
                    $headers = [];
                }

                $position = strpos(
                    $headerLine,
                    ':'
                );

                if ($position !== false) {
                    $name = strtolower(trim(
                        substr($headerLine, 0, $position)
                    ));

                    $value = trim(
                        substr($headerLine, $position + 1)
                    );

                    $headers[$name] = $value;
                }

                return $length;
            },
        ]);

        $body = curl_exec($curl);
        $curlError = curl_errno($curl);
        $statusCode = (int)curl_getinfo(
            $curl,
            CURLINFO_HTTP_CODE
        );

        curl_close($curl);

        $transportFailure = $body === false;

        $retryableStatus = in_array(
            $statusCode,
            [408, 429, 500, 502, 503, 504],
            true
        );

        if (!$transportFailure && !$retryableStatus) {
            return [
                'status' => $statusCode,
                'body' => $body,
                'headers' => $headers,
                'attempts' => $attempt,
            ];
        }

        if ($attempt === $maxAttempts) {
            throw new RuntimeException(
                'API request failed after '
                . $attempt
                . ' attempts. HTTP '
                . $statusCode
                . ', cURL error '
                . $curlError
            );
        }

        $delayMs = min(
            30000,
            1000 * (2 ** ($attempt - 1))
        );

        $retryAfter = $headers['retry-after'] ?? null;

        if ($retryAfter !== null) {
            if (ctype_digit($retryAfter)) {
                $delayMs = (int)$retryAfter * 1000;
            } else {
                $timestamp = strtotime($retryAfter);

                if ($timestamp !== false) {
                    $delayMs = max(
                        0,
                        $timestamp - time()
                    ) * 1000;
                }
            }
        } else {
            $delayMs = random_int(
                0,
                (int)$delayMs
            );
        }

        // Do not block this worker indefinitely.
        if ($delayMs > 30000) {
            throw new RuntimeException(
                'Retry deferred: waiting time exceeds '
                . 'the synchronous retry budget.'
            );
        }

        usleep((int)$delayMs * 1000);
    }

    throw new RuntimeException(
        'Unexpected retry state.'
    );
}

如何使用它

<?php
declare(strict_types=1);

try {
    $result = apiGet(
        'https://api.example.com/products'
    );

    if ($result['status'] !== 200) {
        throw new RuntimeException(
            'Unexpected HTTP status: '
            . $result['status']
        );
    }

    $products = json_decode(
        $result['body'],
        true,
        512,
        JSON_THROW_ON_ERROR
    );

    echo 'API request completed after '
        . $result['attempts']
        . ' attempt(s).';

} catch (Throwable $exception) {
    error_log($exception->getMessage());
}

此实现有意仅限于向受信任的 API 端点发起 GET 请求。

它不会自动重试 POST、PUT、PATCH 或 DELETE 操作,因为这些操作需要额外的保护措施。

它还会将不可重试的 HTTP 响应返回给调用方,由调用方决定如何处理它们。

对于生产系统,你还应验证响应类型、强制实施响应大小限制,并区分可重试的传输错误与永久性的 TLS 或配置失败。

6. 为什么重试 POST 请求可能很危险

想象一个电子商务应用发送此请求:

POST /api/orders
Content-Type: application/json

{
  "product_id": 42,
  "quantity": 1
}

远程 API 创建了订单,但连接在你的应用收到响应之前中断了。

你的应用看到超时。

订单失败了吗?

不一定。订单可能已经存在。

如果你的应用立即重试,它可能会创建第二个订单。

这就是为什么超时并不证明操作在服务器上失败了。

在受支持时使用幂等键

有些 API 支持幂等键。

例如:

Idempotency-Key: order-8f7a2c

当 API 提供了有文档说明的幂等机制时,对同一逻辑操作的重试复用同一个键可以防止重复处理。

但这种行为因 API 而异。添加 Idempotency-Key 请求头并不会自动让任意 API 变成幂等的。

对于涉及支付、订单、订阅或数据库修改的操作,请遵循提供方的官方重试和幂等性文档。

当不存在幂等机制时,你可能需要在再次尝试之前查询操作状态或核对结果。

7. 避免在长时间运行的 Web 请求内休眠

Technical workflow illustration

我们的示例使用 usleep() 让重试行为易于理解。

对于时间短且重试预算严格受控的操作,这可以接受。

然而,生产网站不应在等待外部 API 时让 PHP 工作进程被占用数分钟。

假设 API 返回:

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

在 HTTP 请求内等待一小时会是很糟糕的设计。

更好的解决方案是延迟该操作。

例如,存储一个待处理任务:

Job ID: 1842
Status: pending
Attempts: 2
Next attempt: 2026-11-20 14:30:00 UTC

然后,定时工作进程可以在任务符合条件时处理它。

这种方法特别适用于:

  • 产品目录同步。
  • 电子邮件发送。
  • 社交媒体发布。
  • 文档处理。
  • 库存更新。
  • 大型 API 导入。

它还让失败更容易被监控和恢复。

8. 在数据库中存储重试信息

对于由 MariaDB 支持的应用,一个简单的任务表可以如下所示:

CREATE TABLE api_jobs (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    job_type VARCHAR(100) NOT NULL,
    payload_json LONGTEXT NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT 'pending',
    attempts INT UNSIGNED NOT NULL DEFAULT 0,
    next_attempt_at DATETIME NOT NULL,
    last_error TEXT NULL,
    created_at DATETIME NOT NULL,
    updated_at DATETIME NOT NULL,
    INDEX idx_jobs_ready (
        status,
        next_attempt_at
    )
);

工作进程选择满足以下条件的任务:

SELECT id, job_type, payload_json
FROM api_jobs
WHERE status = 'pending'
AND next_attempt_at <= UTC_TIMESTAMP()
ORDER BY next_attempt_at, id
LIMIT 20;

这只是队列实现中的选择部分。

如果多个工作进程可以同时运行,就必须使用适当的事务和锁定策略原子地认领任务,以防止重复处理。

工作进程还应应用最大重试次数,并将永久失败的任务移入需要调查的状态。

对于小型应用,这种基于数据库的方法可能就足够了,无需引入 Redis 或专用消息代理。

9. 记录失败而不暴露敏感数据

有用的 API 日志应回答四个问题:

  1. 哪个操作失败了?
  2. 涉及哪个远程服务?
  3. HTTP 状态或传输错误是什么?
  4. 应用将在何时重试?

例如:

[2026-11-20 13:25:00 UTC]
service=inventory-api
operation=sync-products
status=429
attempt=2
next_retry=2026-11-20T13:26:00Z

避免记录 API 密钥、Bearer 令牌、完整授权头、密码或不必要的个人信息。

如果你需要关联请求,请使用生成的请求标识符。

例如:

$requestId = bin2hex(random_bytes(8));

你可以将此标识符包含在应用日志中,并在受支持时将其发送给远程 API。

10. 在生产环境之前测试你的重试策略

应针对可预测的失败场景测试重试机制。

你不需要等待真实的 API 故障。

本地测试端点可以故意返回特定状态码。

例如:

<?php
declare(strict_types=1);

header('Content-Type: application/json');

http_response_code(429);
header('Retry-After: 3');

echo json_encode([
    'error' => 'rate_limit_exceeded',
]);

仅在本地或受保护的测试环境中运行此端点。

然后验证你的客户端:

  • 能检测 HTTP 429。
  • 读取 Retry-After 请求头。
  • 在重试前等待。
  • 在达到配置的尝试次数后停止。
  • 记录失败而不暴露机密。

使用 HTTP 503 和一个故意变慢的端点重复测试。

还要测试 HTTP 400 响应,以确认客户端不会重试永久性请求错误。

最后,测试一个可能在连接失败前已经成功的操作。这对支付和订单集成至关重要。

11. 可靠 API 集成的生产检查清单

在部署 API 集成之前,请验证以下内容:

检查项 预期行为
连接超时 已定义并测试
整体超时 已定义并测试
HTTP 429 遵守速率限制
HTTP 5xx 有选择地重试
HTTP 4xx 不盲目重试
重试上限 防止无限循环
重试延迟 带抖动的退避
POST 操作 幂等性或结果核对
长时间等待 延迟到工作进程处理
日志 有用、私密、已脱敏
工作进程并发 防止重复执行
永久性失败 可见且可恢复

结论:可靠的 API 需要受控的失败处理

外部 API 从来都不是完全可用的。

即使是维护良好的服务,也可能经历临时过载、网络中断或速率限制。

目标不是消除所有失败,而是让应用在失败发生时以可预测的方式响应。

从合理的超时和显式的 HTTP 错误处理开始。添加带指数退避的有界重试,遵守服务器提供的重试延迟,并避免自动重复可能产生重复数据的操作。

对于更复杂的集成,将重试移入持久化任务队列,而不是保持 Web 请求打开。

这些原则几乎适用于所有现代 PHP 应用,无论你是在构建 CMS 扩展、同步电子商务目录、发送事务性电子邮件,还是集成支付服务。

可靠的 API 客户端不仅知道如何发送请求,还知道何时重试、何时等待以及何时停止。

官方参考资料