# http-client

**Repository Path**: fiberphp/http-client

## Basic Information

- **Project Name**: http-client
- **Description**: 🌐 FiberPHP HTTP 客户端组件 —— 基于 Workerman 的协程 HTTP 客户端，支持连接池、重试、中间件、协程非阻塞，开箱即用。
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-23
- **Last Updated**: 2026-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# fiberphp/http-client

协程友好的 HTTP 客户端，封装 `workerman/http-client`。单例复用连接池，内置自动重试（指数退避）、熔断器、SSRF
防护与请求/响应日志脱敏，协程模式下同步写法、非阻塞执行。

## 环境要求

- PHP >= 8.3
- `ext-json`
- `workerman/http-client` ^3.1
- `fiberphp/container` dev-master

## 安装

```bash
composer require fiberphp/http-client
```

## 快速开始

```php
use FiberPHP\HttpClient\Http;
use FiberPHP\Container\Container;

// 从容器获取单例
$http = Container::getInstance()->get(Http::class);

// GET
$response = $http->get('https://api.example.com/users', ['Accept' => 'application/json']);
$response->getStatusCode();   // 200
$body = $response->getBody()->__toString();

// POST（数组自动 JSON 序列化）
$response = $http->post('https://api.example.com/users', ['name' => 'tom'], [
    'Authorization' => 'Bearer token',
]);

// 其他动词
$http->put($url, $data);
$http->patch($url, $data);
$http->delete($url);
$http->head($url);
```

### 原始请求

`request()` 暴露完整选项，可控制 method / data / headers / proxy：

```php
$response = $http->request($url, [
    'method'  => 'POST',
    'data'    => $payload,
    'headers' => ['Content-Type' => 'application/json'],
    'proxy'   => 'tcp://127.0.0.1:7890',
]);
```

## 配置说明

配置默认值内置于 `Http`，框架项目可通过 `config/http_client.php` 覆盖（与默认值递归合并）：

```php
return [
    // 连接池
    'max_conn_per_addr' => 128,
    'keepalive_timeout' => 15,
    'connect_timeout'   => 30,
    'timeout'           => 30,

    // 自动重试（指数退避）
    'retry' => [
        'max_attempts' => 3,
        'delay_ms'     => 200,
        'multiplier'   => 2.0,
        'max_delay_ms' => 5000,
    ],

    // 熔断器（按 host 滑动窗口统计失败率）
    'circuit_breaker' => [
        'enable'                       => true,
        'failure_threshold'            => 0.5,
        'window_size'                  => 10,
        'open_duration'                => 30,
        'half_open_success_threshold'  => 3,
    ],

    // SSRF 防护（接入用户可控 URL 时应显式开启）
    'ssrf' => [
        'enable'          => false,
        'allowed_schemes' => ['http', 'https'],
        'block_private'   => true,
        'allow_hosts'     => [],
        'validator'       => null,
        'redirect_max'    => 5,
    ],
];
```

## 特性

| 能力       | 说明                                                                                   |
|------------|----------------------------------------------------------------------------------------|
| 连接池复用 | 单例 `Client`，`max_conn_per_addr` 同地址复用连接                                      |
| 自动重试   | 幂等方法对 5xx/429/连接异常指数退避重试；非幂等方法对 5xx 不重试                       |
| 熔断器     | 按 host 滑动窗口统计失败率，超阈值开路 → 半开探测 → 连续成功关闭                       |
| SSRF 防护  | scheme 白名单、私网/保留地址拦截、DNS 解析防 rebinding、重定向逐跳校验、跨域剥离敏感头 |
| 日志脱敏   | authorization/cookie/token 等 14 个请求头、15 个 JSON 字段递归脱敏，body 截断          |
| 链路追踪   | 安装 `fiberphp/tracing` 后自动注入 B3 传播头并记录 Client Span                         |
| 协程 sleep | 重试退避优先 `Workerman\Timer::sleep`，无 Timer 退化为 `usleep`                        |

## 依赖说明

| 依赖                   | 说明                                                                  |
|------------------------|-----------------------------------------------------------------------|
| PHP >= 8.3             | 运行环境要求                                                          |
| `ext-json`             | JSON 编解码                                                           |
| `workerman/http-client` | 底层 HTTP 客户端                                                     |
| `fiberphp/container`   | 容器解析单例、ConfigRepository、LoggerInterface                       |
| `fiberphp/config`      | （suggest）从 `config/http_client.php` 读取用户配置                  |
| `fiberphp/log`         | （suggest）请求/响应日志，未安装时降级为 NullLogger                   |
| `fiberphp/tracing`     | （suggest）链路追踪，B3 传播头注入 + Client Span                      |

## 目录结构

```
src/
├── Exception/
│   └── HttpClientException.php    # HTTP 客户端异常（SSRF 拦截 / 熔断开启）
└── Http.php                        # HTTP 客户端（连接池 / 重试 / 熔断 / SSRF / 脱敏 / 追踪）
```

命名空间为 `FiberPHP\HttpClient\`（PSR-4，对应 `src/` 目录）。

## License

MIT License (c) 2026 庞斌，详见 [LICENSE](LICENSE)。