详解 Kode HTTP Client：支持 PSR 标准与 Swoole/Swow 的现代化高性能 PHP 客户端

Kode HTTP Client 是一个为现代化 PHP 应用设计的高性能 HTTP 客户端。它的一大亮点在于能够无缝适配多种运行时环境，包括传统的 FPM、CLI，以及高性能的 Swoole 和 Swow 协程环境，并支持 Fiber。

特性

• ✅ 多运行时支持（FPM、CLI、Swoole、Swow、Fiber）
• ✅ 自动环境检测与驱动切换
• ✅ PSR-7/PSR-18 兼容
• ✅ 支持请求上下文传递（使用 kode/context）
• ✅ 中间件支持（重试、超时、日志等）
• ✅ 异常处理
• ✅ 简洁的 API

安装

通过 Composer 即可快速安装：

composer require kode/http-client

使用

基本使用

其 API 设计遵循 PSR-18 标准，使用起来非常直观：

use Kode\HttpClient\Factory;
use GuzzleHttp\Psr7\Request;

// 创建客户端
$client = Factory::create();

// 创建请求
$request = new Request('GET', 'https://httpbin.org/get');

// 发送请求
$response = $client->sendRequest($request);

echo $response->getStatusCode(); // 200
echo $response->getBody();       // 响应内容

使用上下文

通过 kode/context 包提供的上下文对象，可以方便地为单个请求传递配置，如超时和重试次数：

use Kode\HttpClient\Factory;
use Kode\HttpClient\Context\Context;
use GuzzleHttp\Psr7\Request;

// 创建客户端
$client = Factory::create();

// 创建请求
$request = new Request('GET', 'https://httpbin.org/get');

// 创建上下文
$context = new Context();
$context = $context->withTimeout(5.0); // 5秒超时
$context = $context->withRetryCount(3); // 最大重试次数

// 发送请求
$response = $client->sendRequest($request, $context);

增强的上下文功能

我们扩展了上下文功能，添加了以下方法：

• getTimeout() 和 withTimeout()：获取和设置请求超时时间
• getRetryCount() 和 withRetryCount()：获取和设置重试次数

使用中间件

在创建客户端时传入配置数组，可以自动启用一系列实用的内置中间件，极大地简化了常见功能的实现。如果你正在寻找更多 PHP 相关的实用工具或框架集成思路，不妨来 云栈社区 的对应板块逛逛。

use Kode\HttpClient\Factory;
use Kode\Context\Context;
use GuzzleHttp\Psr7\Request;

// 创建带配置的客户端
$client = Factory::create([
    'timeout' => 10.0,     // 默认超时时间
    'retries' => 3,        // 最大重试次数
    'logger' => function(string $message) {
        echo "[" . date('Y-m-d H:i:s') . "] " . $message . PHP_EOL;
    },
    'auth' => [            // 认证配置
        'type' => 'bearer',
        'credential' => 'your-bearer-token'
    ],
    'rate_limit' => [      // 限流配置
        'capacity' => 10,
        'rate' => 1
    ],
    'cache' => true // 启用缓存
]);

// 创建请求
$request = new Request('GET', 'https://httpbin.org/get');

// 发送请求（将自动应用所有配置的中间件）
$response = $client->sendRequest($request);

认证中间件

支持 Bearer Token 和 API Key 认证：

// Bearer Token 认证
$client = Factory::create([
    'auth' => [
        'type' => 'bearer',
        'credential' => 'your-bearer-token'
    ]
]);

// API Key 认证
$client = Factory::create([
    'auth' => [
        'type' => 'api_key',
        'credential' => 'your-api-key',
        'header' => 'X-API-Key' // 可选，默认为 X-API-Key
    ]
]);

限流中间件

使用令牌桶算法实现请求频率限制：

$client = Factory::create([
    'rate_limit' => [
        'capacity' => 10,  // 桶的容量
        'rate' => 1 // 每秒生成的令牌数
    ]
]);

缓存中间件

自动缓存响应以提高性能：

$client = Factory::create([
    'cache' => true // 启用缓存
]);

重试中间件（增强版）

改进的重试中间件现在支持对所有异常类型的重试，而不仅仅是网络异常：

// 手动添加重试中间件
use Kode\HttpClient\Middleware\RetryMiddleware;

$client = new \Kode\HttpClient\HttpClient();
$client->addMiddleware(new RetryMiddleware(
    3,      // 最大重试次数
    100,    // 初始退避时间（毫秒）
    2.0 // 退避乘数
));

驱动支持

库会自动检测运行环境并选择最优的驱动，也支持手动指定。

运行环境	推荐驱动	说明
Swoole 启用	SwooleDriver	高性能、原生协程支持
Amp 可用	AmpDriver	基于事件循环的纯 PHP 实现
默认环境	CurlDriver	基于 curl 扩展的同步实现

文档

• 使用指南 - 详细说明如何使用客户端的所有功能
• API 文档 - 完整的 API 参考

Kode HTTP Client 通过简洁的 API、强大的中间件生态和对多运行时的原生支持，为不同场景下的 PHP HTTP 通信需求提供了一个可靠的解决方案。其项目代码和完整文档已托管在 GitHub，欢迎开发者访问查阅、使用乃至参与贡献。