README

一个现代化、高性能的 PHP HTTP 客户端，支持多运行时环境（FPM、CLI、Swoole、Swow、Fiber）。

特性

✅ 多运行时支持 - 自动检测运行环境，支持 FPM、CLI、Swoole、Swow、Fiber
✅ 自动驱动切换 - 根据环境自动选择最优驱动
✅ PSR-7/PSR-18 兼容 - 完全遵循 PSR 标准
✅ 上下文管理 - 使用 kode/context 进行请求上下文传递
✅ 中间件机制 - 内置重试、超时、日志、认证、限流、缓存等中间件
✅ PHP 8.3+ 支持 - 兼容 PHP 8.4 / 8.5 新特性
✅ Fiber 支持 - 原生 Fiber 驱动，支持 kode/fibers 包集成
✅ 类型安全 - 完整的类型声明和静态分析支持

安装

composer require kode/http-client

快速开始

基本使用

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();       // 响应内容

使用 Fiber 驱动

use Kode\HttpClient\Factory;

// 创建 Fiber 驱动的客户端
$client = Factory::createFiber([
    'timeout' => 10.0,
    'retries' => 3,
]);

// 或指定驱动类型
$client = Factory::create([
    'driver' => Factory::DRIVER_FIBER,
]);

使用配置选项

use Kode\HttpClient\Factory;

// 创建带配置的客户端
$client = Factory::create([
    'driver' => 'fiber',   // 驱动类型（auto|curl|swoole|amp|fiber）
    '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,       // 启用缓存
    'trace' => true        // 链路追踪：自动注入 traceparent / X-Context-* 头
]);

// 发送请求
$request = new \GuzzleHttp\Psr7\Request('GET', 'https://httpbin.org/get');
$response = $client->sendRequest($request);

驱动支持

运行环境	推荐驱动	说明
Fiber 环境	`FiberDriver`	PHP 8.3+ 原生 Fiber 支持，自动协程切换
Swoole 协程	`SwooleDriver`	高性能、原生协程支持
Amp 环境	`AmpDriver`	基于事件循环的异步实现
默认环境	`CurlDriver`	基于 curl 扩展的同步实现

驱动选择优先级

自动模式下，驱动选择优先级为：

SwooleDriver - 如果在 Swoole 协程环境中
FiberDriver - 如果 PHP 8.3+ 且 curl 扩展可用
AmpDriver - 如果 Amp HTTP 客户端可用
CurlDriver - 默认回退

手动选择驱动

use Kode\HttpClient\Factory;
use Kode\HttpClient\HttpClient;
use Kode\HttpClient\Driver\CurlDriver;
use Kode\HttpClient\Driver\FiberDriver;
use Kode\HttpClient\Driver\SwooleDriver;

// 方式一：通过工厂配置
$client = Factory::create(['driver' => Factory::DRIVER_FIBER]);

// 方式二：使用工厂快捷方法
$client = Factory::createFiber();
$client = Factory::createSwoole();
$client = Factory::createAmp();

// 方式三：手动实例化
$client = new HttpClient(new FiberDriver());

中间件

认证中间件

支持 Bearer Token 和 API Key 认证：

use Kode\HttpClient\Middleware\AuthMiddleware;
use Kode\HttpClient\Middleware\MiddlewareStack;
use Kode\HttpClient\Factory;

// 方式一：通过工厂配置
$client = Factory::create([
    'auth' => [
        'type' => 'bearer',
        'credential' => 'your-bearer-token'
    ]
]);

// 方式二：手动添加中间件
$stack = new MiddlewareStack();
$stack->add(AuthMiddleware::bearer('your-bearer-token'));
// 或
$stack->add(AuthMiddleware::apiKey('your-api-key', 'X-API-Key'));

$client = Factory::createWithMiddleware($stack);

限流中间件

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

use Kode\HttpClient\Middleware\RateLimitMiddleware;

// 容量 10，每秒生成 1 个令牌
$middleware = new RateLimitMiddleware(10, 1);

// 阻塞模式（等待可用令牌）
$middleware = new RateLimitMiddleware(10, 1, true);

缓存中间件

自动缓存 GET 请求响应：

use Kode\HttpClient\Middleware\CacheMiddleware;

// 默认缓存 300 秒
$middleware = new CacheMiddleware();

// 自定义缓存时间
$middleware = new CacheMiddleware(600); // 10 分钟

// 获取缓存统计
$stats = $middleware->getCacheStats();
// ['total' => 10, 'valid' => 8, 'expired' => 2]

// 清除缓存
$middleware->clearCache();

重试中间件

支持指数退避策略的自动重试：

use Kode\HttpClient\Middleware\RetryMiddleware;

// 最多重试 3 次，初始退避 100ms，退避乘数 2.0
$middleware = new RetryMiddleware(3, 100, 2.0);

超时中间件

为请求设置超时时间：

use Kode\HttpClient\Middleware\TimeoutMiddleware;

// 默认超时 30 秒
$middleware = new TimeoutMiddleware(30.0);

日志中间件

记录请求和响应信息：

use Kode\HttpClient\Middleware\LoggingMiddleware;

$middleware = new LoggingMiddleware(function (string $message) {
    error_log($message);
});

链路追踪中间件

基于 kode/context 3.x 的 toHeaders() / fromHeaders()，自动把当前链路上下文（W3C traceparent / tracestate 以及 X-Context-* 私有头）注入出站请求，打通跨服务全链路追踪：

use Kode\HttpClient\Middleware\TracingMiddleware;

// 仅注入出站请求头
$middleware = new TracingMiddleware();

// 同时把下游响应里的 X-Context-* 上下文回写到当前上下文
$middleware = new TracingMiddleware(propagateResponse: true);

开启链路追踪需在请求前调用 Kode\Context\Context::startTrace()（或复用已有链路）；未开启时仍会透传已存在的 X-Context-* 头（如请求 ID、关联 ID），但不会注入 W3C 头。可通过工厂一键启用：

use Kode\HttpClient\Factory;

// 注入出站链路头
$client = Factory::create(['trace' => true]);

// 同时回写下游上下文
$client = Factory::create(['trace' => ['propagate_response' => true]]);

上下文管理

使用 kode/context 进行上下文传递：

use Kode\HttpClient\Context\Context;

// 设置超时时间
Context::setTimeout(5.0);

// 获取超时时间
$timeout = Context::getTimeout();

// 设置重试次数
Context::setRetryCount(3);

// 获取请求耗时
$elapsed = Context::getElapsedTime(); // 毫秒

// 初始化上下文
$requestId = Context::initialize([
    'timeout' => 10.0,
    'retry_count' => 3,
]);

// 清除上下文
Context::clear();

与 kode/fibers 集成

本包支持与 kode/fibers 包无缝集成：

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

// 在 Fiber 池中并发发送请求
$results = Fibers::batch(
    ['https://httpbin.org/get', 'https://httpbin.org/post'],
    fn(string $url) => Factory::createFiber()
        ->sendRequest(new Request('GET', $url))
        ->getBody()
        ->getContents(),
    2 // 并发数
);

异常处理

use Kode\HttpClient\Exception\NetworkException;
use Kode\HttpClient\Exception\RequestException;

try {
    $response = $client->sendRequest($request);
} catch (NetworkException $e) {
    // 网络错误
    echo '网络错误: ' . $e->getMessage();
    echo '请求 URI: ' . $e->getRequestUri();
} catch (RequestException $e) {
    // 请求格式错误
    echo '请求错误: ' . $e->getMessage();
} catch (\Exception $e) {
    // 其他错误
    echo '错误: ' . $e->getMessage();
}

项目结构

src/
├── Config/
│   └── TransportOptions.php        # 传输层配置
├── Context/
│   └── Context.php                 # HTTP 上下文辅助类
├── Driver/
│   ├── DriverInterface.php         # 驱动接口
│   ├── ConcurrentDriverInterface.php # 并发驱动接口
│   ├── CurlDriver.php              # Curl 驱动
│   ├── FiberDriver.php             # Fiber 驱动
│   ├── SwooleDriver.php            # Swoole 驱动
│   ├── SwowDriver.php              # Swow 驱动
│   └── AmpDriver.php               # Amp 驱动
├── Exception/                      # 异常体系（含熔断/限流/超时等）
├── Message/
│   └── MessageFactory.php          # PSR-17 消息工厂
├── Middleware/
│   ├── MiddlewareInterface.php     # 中间件接口
│   ├── MiddlewareStack.php         # 中间件栈
│   ├── AuthMiddleware.php          # 认证中间件
│   ├── CacheMiddleware.php         # 缓存中间件
│   ├── CircuitBreakerMiddleware.php # 熔断中间件
│   ├── HeadersMiddleware.php       # 默认请求头中间件
│   ├── LoggingMiddleware.php        # 日志中间件
│   ├── RateLimitMiddleware.php     # 限流中间件
│   ├── RetryMiddleware.php          # 重试中间件
│   ├── TimeoutMiddleware.php        # 超时中间件
│   └── TracingMiddleware.php        # 链路追踪中间件
├── Request/
│   └── RequestBuilder.php          # 语义化请求构建器
├── Response/
│   └── HttpResponse.php            # 响应装饰器（便捷方法）
├── Factory.php              # 客户端工厂
├── HttpClient.php           # HTTP 客户端实现
└── HttpClientInterface.php  # HTTP 客户端接口

示例

example/ 下提供了可直接运行的示例：

文件	说明	联网
`example/quickstart.php`	基础用法：GET/POST、JSON/表单、base_uri、单次超时	需要
`example/middleware.php`	中间件装配、自定义中间件、各中间件运行时状态	不需要
`example/concurrent.php`	`sendConcurrent()` / `pool()` 的「全部落定」语义	不需要
`example/tracing.php`	链路追踪头注入与安全降级	不需要

php example/middleware.php

不联网的示例使用桩驱动（实现 DriverInterface），结果确定，也是单元测试的惯用写法。

测试

# 运行全部测试（自动发现 tests/ 下所有 *Test.php）
composer test

# 生成测试覆盖率报告
composer test-coverage

要求

PHP >= 8.3
ext-curl（CurlDriver 和 FiberDriver 需要）
kode/context ^3.1
psr/http-message ^2.0
psr/http-client ^1.0

可选依赖

ext-swoole - Swoole 协程支持
ext-swow - Swow 协程支持
amphp/http-client - Amp 异步 HTTP 客户端
kode/fibers - Fiber 协程池和调度器
guzzlehttp/psr7 - PSR-7 消息实现

许可证

MIT

作者

Kode Team 382601296@qq.com

kode / http-client

Maintainers

Package info

Statistics

Security