PHP类代码
<?php
declare(strict_types=1);
namespace App\Http;
use CURLFile;
use Psr\Log\LoggerInterface;
use RuntimeException;
/**
* Class RestHttpClient
*
* 轻量级 HTTP 客户端封装：
* - 提供 GET/POST/PUT/DELETE 通用方法
* - 内置：重试（指数退避+抖动）、超时控制、连接池（cURL Share 复用连接）、统一错误处理
* - 支持：签名 Header、JSON/Form/Multipart（文件）/原始流 提交
* - 集中日志、可注入 TraceId 追踪
*
* 说明：
* 1) 依赖 ext-curl；连接池基于 cURL Share 复用 DNS/SSL 会话/连接
* 2) 默认对 429/5xx 做重试，对 GET/PUT/DELETE 等幂等方法自动重试；POST 如需重试需显式开启 idempotent=true
* 3) 默认对 4xx/5xx 抛出异常（可通过 throw_on_http_error=false 改为返回响应）
*/
final class RestHttpClient
{
private const DEFAULT_USER_AGENT = 'RestHttpClient/1.0 (+https://example.com)';
private const DEFAULT_TRACE_HEADER = 'X-Trace-Id';
/** @var resource|null */
private static $curlShare = null;
private readonly ?LoggerInterface $logger;
/** @var array<string,string> */
private array $defaultHeaders;
/** @var array<string,mixed> */
private array $clientConfig;
private readonly ?SignerInterface $signer;
private readonly TraceIdProviderInterface $traceIdProvider;
/**
* @param array<string,string> $defaultHeaders 默认公共头
* @param array<string,mixed> $clientConfig 客户端级配置（可被每次调用 options 覆盖）
* 可选键：
* - base_uri: string 基础URL（相对路径将拼接）
* - connect_timeout_ms: int 连接超时（默认 2000ms）
* - timeout_ms: int 整体超时（默认 5000ms）
* - max_attempts: int 最大重试次数（默认 3）
* - retry_backoff_factor: float 退避倍数（默认 2.0）
* - retry_delay_ms: int 初始重试延迟（默认 100ms）
* - max_retry_delay_ms: int 最大重试延迟（默认 2000ms）
* - retry_on_status: int[] 需重试的HTTP状态（默认 [429,500,502,503,504]）
* - retry_on_network_errors: bool 网络错误是否重试（默认 true）
* - retry_on_methods: string[] 幂等方法（默认 ['GET','HEAD','PUT','DELETE','OPTIONS']）
* - follow_redirects: bool 是否跟随重定向（默认 true）
* - max_redirects: int 最大重定向次数（默认 3）
* - enable_connection_pool: bool 开启连接池（默认 true）
* - throw_on_http_error: bool 非2xx是否抛异常（默认 true）
* - trace_header: string 追踪头名称（默认 X-Trace-Id）
* - auto_sign: bool 是否自动签名（默认 false）
*/
public function __construct(
?LoggerInterface $logger = null,
?SignerInterface $signer = null,
?TraceIdProviderInterface $traceIdProvider = null,
array $defaultHeaders = [],
array $clientConfig = []
) {
if (!\extension_loaded('curl')) {
throw new RuntimeException('ext-curl is required by RestHttpClient.');
}
$this->logger = $logger;
$this->signer = $signer;
$this->traceIdProvider = $traceIdProvider ?? new UuidV4TraceIdProvider();
$this->defaultHeaders = $this->normalizeHeaders(array_merge([
'User-Agent' => self::DEFAULT_USER_AGENT,
'Accept' => '*/*',
'Connection' => 'keep-alive',
], $defaultHeaders));
$this->clientConfig = array_merge([
'base_uri' => '',
'connect_timeout_ms' => 2000,
'timeout_ms' => 5000,
'max_attempts' => 3,
'retry_backoff_factor' => 2.0,
'retry_delay_ms' => 100,
'max_retry_delay_ms' => 2000,
'retry_on_status' => [429, 500, 502, 503, 504],
'retry_on_network_errors' => true,
'retry_on_methods' => ['GET', 'HEAD', 'PUT', 'DELETE', 'OPTIONS'],
'follow_redirects' => true,
'max_redirects' => 3,
'enable_connection_pool' => true,
'throw_on_http_error' => true,
'trace_header' => self::DEFAULT_TRACE_HEADER,
'auto_sign' => false,
], $clientConfig);
if ($this->clientConfig['enable_connection_pool']) {
$this->initCurlShare();
}
}
/**
* 发送 GET 请求
*
* @param array<string,scalar|array|null> $query
* @param array<string,string> $headers
* @param array<string,mixed> $options
* @throws RestHttpException
*/
public function get(string $url, array $query = [], array $headers = [], array $options = []): RestHttpResponse
{
return $this->request('GET', $url, [
'query' => $query,
'headers' => $headers,
], $options);
}
/**
* 发送 POST 请求
*
* Body 提交方式通过 options 指定：
* - json: array|object -> JSON 编码
* - form_params: array -> application/x-www-form-urlencoded
* - multipart: array<array{name:string,contents:string|CURLFile,filename?:string,headers?:array<string,string>}>
* - raw: string -> 原始字节流（可自行设置 Content-Type）
*
* @param array<string,string> $headers
* @param array<string,mixed> $options
* @throws RestHttpException
*/
public function post(string $url, array $headers = [], array $options = []): RestHttpResponse
{
return $this->request('POST', $url, [
'headers' => $headers,
], $options);
}
/**
* 发送 PUT 请求
*
* @param array<string,string> $headers
* @param array<string,mixed> $options
* @throws RestHttpException
*/
public function put(string $url, array $headers = [], array $options = []): RestHttpResponse
{
return $this->request('PUT', $url, [
'headers' => $headers,
], $options);
}
/**
* 发送 DELETE 请求
*
* @param array<string,scalar|array|null> $query
* @param array<string,string> $headers
* @param array<string,mixed> $options
* @throws RestHttpException
*/
public function delete(string $url, array $query = [], array $headers = [], array $options = []): RestHttpResponse
{
return $this->request('DELETE', $url, [
'query' => $query,
'headers' => $headers,
], $options);
}
/**
* 通用请求入口
*
* options 支持：
* - query: array 查询参数
* - headers: array 额外头
* - json: array|object JSON 体
* - form_params: array 表单体
* - multipart: array 表单-文件体（见 post() 注释）
* - raw: string 原始字节
* - idempotent: bool POST 是否视为可重试（默认 false）
* - sign: bool 是否签名（默认 由 auto_sign 控制）
* - timeout_ms / connect_timeout_ms: int 覆盖超时
* - max_attempts / retry_backoff_factor / retry_delay_ms / max_retry_delay_ms / retry_on_status / retry_on_network_errors / retry_on_methods
* - follow_redirects / max_redirects
* - throw_on_http_error: bool 覆盖行为
* - trace_id / trace_header: 自定义追踪
*
* @param array{query?:array,headers?:array} $params
* @param array<string,mixed> $options
* @throws RestHttpException
*/
public function request(string $method, string $url, array $params = [], array $options = []): RestHttpResponse
{
$method = strtoupper($method);
$t0 = \hrtime(true);
// 合并配置
$cfg = $this->mergeOptions($this->clientConfig, $options);
// 组装 URL（base_uri + path + query）
$uri = $this->buildUrl($url, $cfg['base_uri'] ?? '', $params['query'] ?? $options['query'] ?? []);
// 头部合并与注入 TraceId
$traceHeader = (string)($cfg['trace_header'] ?? self::DEFAULT_TRACE_HEADER);
$traceId = (string)($options['trace_id'] ?? $this->traceIdProvider->getTraceId());
$headers = $this->normalizeHeaders(array_merge(
$this->defaultHeaders,
$params['headers'] ?? [],
$options['headers'] ?? []
));
if ($traceHeader !== '') {
$headers[$traceHeader] = $traceId;
}
// Body 构建（互斥：json | form_params | multipart | raw）
$bodyTuple = $this->buildBody($options, $headers);
$postFields = $bodyTuple['post_fields'];
$rawBody = $bodyTuple['raw_body'];
$headers = $bodyTuple['headers'];
// 签名（如启用）
$shouldSign = isset($options['sign']) ? (bool)$options['sign'] : (bool)$cfg['auto_sign'];
if ($shouldSign && $this->signer !== null) {
$sigHeaders = $this->signer->sign($method, $uri, $headers, $rawBody);
$headers = $this->normalizeHeaders(array_merge($headers, $sigHeaders));
}
$attempt = 0;
$maxAttempts = max(1, (int)$cfg['max_attempts']);
$retryableMethods = array_map('strtoupper', (array)$cfg['retry_on_methods']);
$idempotent = in_array($method, $retryableMethods, true) || (bool)($options['idempotent'] ?? false);
$lastException = null;
$response = null;
while ($attempt < $maxAttempts) {
$attempt++;
try {
$response = $this->executeCurl(
method: $method,
url: $uri,
headers: $headers,
postFields: $postFields,
rawBody: $rawBody,
connectTimeoutMs: (int)$cfg['connect_timeout_ms'],
timeoutMs: (int)$cfg['timeout_ms'],
followRedirects: (bool)$cfg['follow_redirects'],
maxRedirects: (int)$cfg['max_redirects'],
withConnectionPool: (bool)$cfg['enable_connection_pool'],
);
// 非 2xx 处理
if ($response->statusCode < 200 || $response->statusCode >= 300) {
$shouldThrow = (bool)$cfg['throw_on_http_error'];
$shouldRetry = $this->shouldRetryHttp(
status: $response->statusCode,
retryOnStatus: (array)$cfg['retry_on_status']
);
// 记录
$this->logHttp($method, $uri, $traceId, $attempt, $t0, $response->statusCode, $shouldRetry);
if ($shouldRetry && $idempotent && $attempt < $maxAttempts) {
$this->sleepBackoff($attempt, (int)$cfg['retry_delay_ms'], (float)$cfg['retry_backoff_factor'], (int)$cfg['max_retry_delay_ms']);
continue;
}
if ($shouldThrow) {
throw RestHttpException::httpError(
message: 'HTTP error response',
method: $method,
uri: $uri,
statusCode: $response->statusCode,
headers: $response->headers,
body: $response->body,
traceId: $traceId
);
}
} else {
// 正常 2xx
$this->logHttp($method, $uri, $traceId, $attempt, $t0, $response->statusCode, false);
}
return $response;
} catch (RestHttpException $e) {
$lastException = $e;
$isNetwork = $e->isNetworkError();
$retryNet = (bool)$cfg['retry_on_network_errors'];
$shouldRetry = $isNetwork && $retryNet && ($idempotent || (bool)($options['idempotent'] ?? false));
$this->logException($method, $uri, $traceId, $attempt, $t0, $e, $shouldRetry);
if ($shouldRetry && $attempt < $maxAttempts) {
$this->sleepBackoff($attempt, (int)$cfg['retry_delay_ms'], (float)$cfg['retry_backoff_factor'], (int)$cfg['max_retry_delay_ms']);
continue;
}
throw $e;
} catch (\Throwable $e) {
$lastException = $e;
$wrapped = RestHttpException::networkError(
message: $e->getMessage(),
method: $method,
uri: $uri,
traceId: $traceId,
previous: $e
);
$retryNet = (bool)$cfg['retry_on_network_errors'];
$shouldRetry = $retryNet && ($idempotent || (bool)($options['idempotent'] ?? false));
$this->logException($method, $uri, $traceId, $attempt, $t0, $wrapped, $shouldRetry);
if ($shouldRetry && $attempt < $maxAttempts) {
$this->sleepBackoff($attempt, (int)$cfg['retry_delay_ms'], (float)$cfg['retry_backoff_factor'], (int)$cfg['max_retry_delay_ms']);
continue;
}
throw $wrapped;
}
}
// 理论上不会到此
if ($lastException instanceof RestHttpException) {
throw $lastException;
}
throw RestHttpException::networkError(
message: 'Unknown error after retries',
method: $method,
uri: $uri,
traceId: $traceId
);
}
/**
* 执行底层 cURL 调用
*
* @param array<string,string> $headers
* @return RestHttpResponse
* @throws RestHttpException
*/
private function executeCurl(
string $method,
string $url,
array $headers,
null|array $postFields,
null|string $rawBody,
int $connectTimeoutMs,
int $timeoutMs,
bool $followRedirects,
int $maxRedirects,
bool $withConnectionPool
): RestHttpResponse {
$ch = \curl_init();
if ($ch === false) {
throw RestHttpException::networkError('Failed to init curl', $method, $url);
}
// Header 处理（数组形式）
$headerLines = [];
foreach ($headers as $k => $v) {
$headerLines[] = $k . ': ' . $v;
}
$responseHeaders = [];
$headerCollector = static function ($ch, string $headerLine) use (&$responseHeaders): int {
$len = strlen($headerLine);
$headerLine = trim($headerLine);
if ($headerLine === '' || strpos($headerLine, ':') === false) {
return $len;
}
[$name, $value] = array_map('trim', explode(':', $headerLine, 2));
$normalized = self::normalizeHeaderName($name);
if (!isset($responseHeaders[$normalized])) {
$responseHeaders[$normalized] = $value;
} else {
// 合并同名多值
$responseHeaders[$normalized] .= ', ' . $value;
}
return $len;
};
$options = [
CURLOPT_URL => $url,
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => $headerLines,
CURLOPT_HEADERFUNCTION => $headerCollector,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT_MS => $connectTimeoutMs,
CURLOPT_TIMEOUT_MS => $timeoutMs,
CURLOPT_FOLLOWLOCATION => $followRedirects,
CURLOPT_MAXREDIRS => $maxRedirects,
CURLOPT_ENCODING => '', // 接受所有压缩
CURLOPT_SSL_VERIFYHOST => 2,
CURLOPT_SSL_VERIFYPEER => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_2TLS, // 优先 HTTP/2（回退到1.1）
CURLOPT_TCP_KEEPALIVE => 1,
CURLOPT_TCP_KEEPIDLE => 30,
CURLOPT_TCP_KEEPINTVL => 10,
];
if ($withConnectionPool && self::$curlShare) {
$options[CURLOPT_SHARE] = self::$curlShare;
}
// 设置 Body
if (in_array($method, ['POST', 'PUT', 'PATCH', 'DELETE'], true)) {
if ($postFields !== null) {
// multipart 或 form
$options[CURLOPT_POSTFIELDS] = $postFields;
} elseif ($rawBody !== null) {
$options[CURLOPT_POSTFIELDS] = $rawBody;
}
}
if (\curl_setopt_array($ch, $options) === false) {
\curl_close($ch);
throw RestHttpException::networkError('Failed to set curl options', $method, $url);
}
$body = \curl_exec($ch);
$errno = \curl_errno($ch);
$error = \curl_error($ch);
$httpCode = (int)(\curl_getinfo($ch, CURLINFO_RESPONSE_CODE) ?: 0);
\curl_close($ch);
if ($errno !== 0) {
throw RestHttpException::networkError(
message: sprintf('cURL error [%d]: %s', $errno, $error ?: 'unknown'),
method: $method,
uri: $url
);
}
return new RestHttpResponse(
statusCode: $httpCode,
headers: $responseHeaders,
body: is_string($body) ? $body : ''
);
}
/**
* 构建请求 Body 并返回 [post_fields, raw_body, headers]
*
* @param array<string,mixed> $options
* @param array<string,string> $headers
* @return array{post_fields:?array, raw_body:?string, headers:array<string,string>}
*/
private function buildBody(array $options, array $headers): array
{
$hasJson = array_key_exists('json', $options);
$hasForm = array_key_exists('form_params', $options);
$hasMultipart = array_key_exists('multipart', $options);
$hasRaw = array_key_exists('raw', $options);
$count = (int)$hasJson + (int)$hasForm + (int)$hasMultipart + (int)$hasRaw;
if ($count > 1) {
throw new RuntimeException('Only one of json, form_params, multipart, raw can be provided.');
}
if ($hasJson) {
$json = $options['json'];
$encoded = json_encode($json, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
$headers = $this->ensureHeader($headers, 'Content-Type', 'application/json; charset=utf-8');
return ['post_fields' => null, 'raw_body' => $encoded, 'headers' => $headers];
}
if ($hasForm) {
$form = (array)$options['form_params'];
$headers = $this->ensureHeader($headers, 'Content-Type', 'application/x-www-form-urlencoded; charset=utf-8');
// 让 cURL 处理 application/x-www-form-urlencoded 时，传入字符串更可靠
$encoded = http_build_query($form, '', '&', PHP_QUERY_RFC3986);
return ['post_fields' => $encoded, 'raw_body' => null, 'headers' => $headers];
}
if ($hasMultipart) {
$parts = (array)$options['multipart'];
// 交由 cURL 构建 multipart/form-data，传数组 + CURLFile 即可
// 注意：不要手动设置 Content-Type（含 boundary），交由 cURL 自动生成更安全
$headers = $this->removeHeader($headers, 'Content-Type');
$postFields = [];
foreach ($parts as $part) {
if (!isset($part['name'], $part['contents'])) {
throw new RuntimeException('Each multipart part requires "name" and "contents".');
}
$name = (string)$part['name'];
$contents = $part['contents'];
if ($contents instanceof CURLFile) {
$postFields[$name] = $contents;
} elseif (is_string($contents)) {
$postFields[$name] = $contents;
} else {
throw new RuntimeException('Multipart contents must be string or CURLFile.');
}
}
return ['post_fields' => $postFields, 'raw_body' => null, 'headers' => $headers];
}
if ($hasRaw) {
$raw = (string)$options['raw'];
// 若未指定 Content-Type，默认二进制流
if (!$this->hasHeader($headers, 'Content-Type')) {
$headers['Content-Type'] = 'application/octet-stream';
}
return ['post_fields' => null, 'raw_body' => $raw, 'headers' => $headers];
}
// 无 Body
return ['post_fields' => null, 'raw_body' => null, 'headers' => $headers];
}
/**
* 指数退避 + 抖动
*/
private function sleepBackoff(int $attempt, int $baseDelayMs, float $factor, int $maxDelayMs): void
{
$delay = (int)min($maxDelayMs, $baseDelayMs * ($factor ** max(0, $attempt - 1)));
// full jitter
$delay = random_int((int)max(0, $delay / 2), $delay);
usleep(max(0, $delay) * 1000);
}
/**
* 是否需要针对 HTTP 状态码重试
* @param int[] $retryOnStatus
*/
private function shouldRetryHttp(int $status, array $retryOnStatus): bool
{
return in_array($status, $retryOnStatus, true);
}
/**
* 构造 URL（支持 base_uri & query）
*
* @param array<string,scalar|array|null> $query
*/
private function buildUrl(string $url, string $baseUri, array $query): string
{
$isAbsolute = (bool)preg_match('#^https?://#i', $url);
$base = rtrim($baseUri, '/');
$path = $isAbsolute ? $url : ($base !== '' ? $base . '/' . ltrim($url, '/') : $url);
if (!empty($query)) {
$qs = http_build_query($query, '', '&', PHP_QUERY_RFC3986);
$path .= (str_contains($path, '?') ? '&' : '?') . $qs;
}
return $path;
}
private function logHttp(string $method, string $url, string $traceId, int $attempt, int $t0, int $status, bool $willRetry): void
{
if (!$this->logger) {
return;
}
$elapsedMs = (int)round((\hrtime(true) - $t0) / 1_000_000);
$level = $willRetry ? 'warning' : 'info';
$context = [
'method' => $method,
'url' => $url,
'status' => $status,
'attempt' => $attempt,
'elapsed_ms' => $elapsedMs,
'trace_id' => $traceId,
'will_retry' => $willRetry,
];
if ($level === 'warning') {
$this->logger->warning('[HTTP] request completed with retryable status', $context);
} else {
$this->logger->info('[HTTP] request completed', $context);
}
}
private function logException(string $method, string $url, string $traceId, int $attempt, int $t0, RestHttpException $e, bool $willRetry): void
{
if (!$this->logger) {
return;
}
$elapsedMs = (int)round((\hrtime(true) - $t0) / 1_000_000);
$context = [
'method' => $method,
'url' => $url,
'attempt' => $attempt,
'elapsed_ms' => $elapsedMs,
'trace_id' => $traceId,
'error_type' => $e->isNetworkError() ? 'network' : 'http',
'status' => $e->getStatusCode(),
'will_retry' => $willRetry,
];
if ($willRetry) {
$this->logger->warning('[HTTP] request failed, will retry: ' . $e->getMessage(), $context);
} else {
$this->logger->error('[HTTP] request failed: ' . $e->getMessage(), $context);
}
}
/**
* 初始化 cURL 连接池（Share）
*/
private function initCurlShare(): void
{
if (self::$curlShare !== null) {
return;
}
$share = \curl_share_init();
if ($share === false) {
// 不可用时静默降级（不抛异常，仍可工作）
return;
}
\curl_share_setopt($share, CURLSHOPT_SHARE, CURL_LOCK_DATA_DNS);
\curl_share_setopt($share, CURLSHOPT_SHARE, CURL_LOCK_DATA_SSL_SESSION);
if (defined('CURL_LOCK_DATA_CONNECT')) {
\curl_share_setopt($share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT);
}
self::$curlShare = $share;
}
/**
* 合并配置（options 覆盖 clientConfig）
*
* @param array<string,mixed> $base
* @param array<string,mixed> $overrides
* @return array<string,mixed>
*/
private function mergeOptions(array $base, array $overrides): array
{
$merged = $base;
foreach ($overrides as $k => $v) {
// 允许覆盖标量、数组（浅合并）、布尔等
if (is_array($v) && isset($merged[$k]) && is_array($merged[$k])) {
$merged[$k] = array_merge($merged[$k], $v);
} else {
$merged[$k] = $v;
}
}
// 局部超时覆盖
if (isset($overrides['timeout_ms'])) {
$merged['timeout_ms'] = (int)$overrides['timeout_ms'];
}
if (isset($overrides['connect_timeout_ms'])) {
$merged['connect_timeout_ms'] = (int)$overrides['connect_timeout_ms'];
}
return $merged;
}
/**
* 规范化头（不区分大小写，键名规范化）
*
* @param array<string,string> $headers
* @return array<string,string>
*/
private function normalizeHeaders(array $headers): array
{
$out = [];
foreach ($headers as $k => $v) {
$out[self::normalizeHeaderName((string)$k)] = (string)$v;
}
return $out;
}
private static function normalizeHeaderName(string $name): string
{
$name = strtolower(trim($name));
return implode('-', array_map(static fn($p) => ucfirst($p), explode('-', $name)));
}
/**
* @param array<string,string> $headers
* @return array<string,string>
*/
private function ensureHeader(array $headers, string $name, string $value): array
{
if (!$this->hasHeader($headers, $name)) {
$headers[self::normalizeHeaderName($name)] = $value;
}
return $headers;
}
/**
* @param array<string,string> $headers
*/
private function hasHeader(array $headers, string $name): bool
{
$n = self::normalizeHeaderName($name);
return array_key_exists($n, $headers);
}
/**
* @param array<string,string> $headers
* @return array<string,string>
*/
private function removeHeader(array $headers, string $name): array
{
$n = self::normalizeHeaderName($name);
unset($headers[$n]);
return $headers;
}
}
/**
* HTTP 响应对象（简化）
*/
final class RestHttpResponse
{
/**
* @param array<string,string> $headers
*/
public function __construct(
public readonly int $statusCode,
public readonly array $headers,
public readonly string $body
) {
}
/**
* 返回大小写不敏感的 Header 值
*/
public function getHeaderLine(string $name): ?string
{
$n = RestHttpClient::class;
$normalize = (new \ReflectionClass($n))->getMethod('normalizeHeaderName');
$normalize->setAccessible(true);
/** @var callable $call */
$call = $normalize->getClosure(new RestHttpClient());
$key = $call($name);
return $this->headers[$key] ?? null;
}
/**
* 尝试 JSON 解析响应体
* @return array<mixed>|null
*/
public function json(): ?array
{
if ($this->body === '') {
return null;
}
try {
$data = json_decode($this->body, true, 512, JSON_THROW_ON_ERROR);
return is_array($data) ? $data : null;
} catch (\JsonException) {
return null;
}
}
}
/**
* 统一异常类型
*/
class RestHttpException extends RuntimeException
{
private ?int $statusCode = null;
private string $method = '';
private string $uri = '';
private string $traceId = '';
private bool $networkError = false;
/** @var array<string,string> */
private array $responseHeaders = [];
private string $responseBody = '';
/**
* @param array<string,string> $headers
*/
public static function httpError(
string $message,
string $method,
string $uri,
int $statusCode,
array $headers,
string $body,
string $traceId = '',
?\Throwable $previous = null
): self {
$ex = new self($message, $statusCode, $previous);
$ex->statusCode = $statusCode;
$ex->method = $method;
$ex->uri = $uri;
$ex->traceId = $traceId;
$ex->responseHeaders = $headers;
$ex->responseBody = $body;
$ex->networkError = false;
return $ex;
}
public static function networkError(
string $message,
string $method,
string $uri,
string $traceId = '',
?\Throwable $previous = null
): self {
$ex = new self($message, 0, $previous);
$ex->statusCode = null;
$ex->method = $method;
$ex->uri = $uri;
$ex->traceId = $traceId;
$ex->networkError = true;
return $ex;
}
public function isNetworkError(): bool
{
return $this->networkError;
}
public function getStatusCode(): ?int
{
return $this->statusCode;
}
public function getMethod(): string
{
return $this->method;
}
public function getUri(): string
{
return $this->uri;
}
public function getTraceId(): string
{
return $this->traceId;
}
/**
* @return array<string,string>
*/
public function getResponseHeaders(): array
{
return $this->responseHeaders;
}
public function getResponseBody(): string
{
return $this->responseBody;
}
}
/**
* 签名器接口：返回应附加的头（如 Authorization、X-Signature 等）
*/
interface SignerInterface
{
/**
* @param array<string,string> $headers
* @return array<string,string> 返回要合并到请求中的签名相关头
*/
public function sign(string $method, string $uri, array $headers, ?string $body): array;
}
/**
* 可插拔的 TraceId 生成器
*/
interface TraceIdProviderInterface
{
public function getTraceId(): string;
}
/**
* 默认 UUIDv4 TraceId 生成器
*/
final class UuidV4TraceIdProvider implements TraceIdProviderInterface
{
public function getTraceId(): string
{
$data = random_bytes(16);
// Version 4
$data[6] = chr((ord($data[6]) & 0x0f) | 0x40);
// Variant RFC 4122
$data[8] = chr((ord($data[8]) & 0x3f) | 0x80);
return vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($data), 4));
}
}
/**
* 示例：HMAC-SHA256 签名器（可选）
*
* 计算规则（仅示例，可按需替换）：
* date = gmdate('Ymd\THis\Z')
* payload = method + "\n" + uri + "\n" + sha256(body)
* signature = base64(hmac_sha256(payload, secret))
* headers:
* X-Date: date
* X-Signature: signature
* X-Key-Id: keyId
*/
final class HmacSha256Signer implements SignerInterface
{
public function __construct(
private readonly string $keyId,
private readonly string $secret
) {
if ($this->keyId === '' || $this->secret === '') {
throw new RuntimeException('Invalid HMAC credentials.');
}
}
/**
* @param array<string,string> $headers
* @return array<string,string>
*/
public function sign(string $method, string $uri, array $headers, ?string $body): array
{
$date = gmdate('Ymd\THis\Z');
$content = $body ?? '';
$hash = hash('sha256', $content, true);
$payload = sprintf("%s\n%s\n%s", strtoupper($method), $uri, bin2hex($hash));
$sig = base64_encode(hash_hmac('sha256', $payload, $this->secret, true));
return [
'X-Date' => $date,
'X-Signature' => $sig,
'X-Key-Id' => $this->keyId,
];
}
}
代码说明
-
命名空间设计思路
- 采用 App\Http 命名空间，表示基础设施层的 HTTP 能力封装，便于在微服务/接口接入场景中统一复用。
- SignerInterface、TraceIdProviderInterface 作为可插拔组件放在同一命名空间下，降低依赖复杂度，调用者可自由替换实现。
-
类结构设计 rationale
- RestHttpClient 是最终类（final），面向使用者提供 GET/POST/PUT/DELETE 以及通用 request 方法，职责清晰：构建请求、控制超时/重试、日志、追踪、签名、错误处理。
- 统一异常 RestHttpException 含网络/HTTP错误上下文，控制器层可统一捕获并映射业务错误语义。
- RestHttpResponse 提供最常用的 status/headers/body，并内置 json() 便捷方法。
- HmacSha256Signer、UuidV4TraceIdProvider 为可选默认实现，示例化可扩展点。
- 连接池通过 cURL Share 复用连接/DNS/SSL 会话，提升吞吐与减少握手开销。
-
主要方法功能说明
- get/post/put/delete：分别封装 HTTP 动词，支持 query/headers/options。
- request：通用入口，支持 body 四种提交方式（json/form_params/multipart/raw）、签名、重试策略、超时、重定向、错误抛出策略、trace 注入等。
- buildBody：构建请求体并设置合适的 Content-Type。
- executeCurl：底层 cURL 执行，开启 keep-alive、HTTP/2（可回退）、压缩、验证 TLS，收集响应头与体。
- sleepBackoff：指数退避+抖动，避免雪崩。
- shouldRetryHttp：定义对特定状态码的重试。
- logHttp/logException：集中日志，包含 method/url/status/attempt/elapsed_ms/trace_id。
-
使用注意事项
- 需要启用 ext-curl 扩展；生产环境请确保 CA 证书正确安装（启用 SSL 验证，已默认开启）。
- multipart 文件上传请使用 CURLFile 实例（安全、现代），不要使用已废弃的 @file 语法。
- 默认对 4xx/5xx 抛出 RestHttpException；如需返回响应自行判断，请在 options 中设置 throw_on_http_error=false。
- POST 默认认为非幂等，不会重试；如确认服务端幂等，设置 options['idempotent']=true。
- base_uri 配置后，传入相对路径会自动拼接；query 参数支持数组，内部按 RFC3986 编码。
- 连接池为进程内（请求内）连接复用，FPM/多进程环境下不跨进程共享，属于 PHP 运行模型限制。
- 如需自定义签名逻辑，实现 SignerInterface 并在构造函数或 options 中开启 sign/auto_sign。
技术要点
-
使用的PHP特性
- 严格类型声明、readonly 构造参数属性、联合类型/类型提示、命名参数调用、JSON_THROW_ON_ERROR、hrtime 高精度计时。
- 安全的随机 UUIDv4 生成（random_bytes）。
-
设计模式应用
- 策略模式：SignerInterface、TraceIdProviderInterface 可替换实现。
- 适配/封装：对 cURL 的细节进行封装，暴露统一语义（超时、重试、连接池、错误）。
-
性能优化考虑
- cURL Share 复用 DNS 缓存、SSL 会话与连接，减少 TLS/握手成本。
- HTTP/2 优先、启用压缩、keep-alive。
- 指数退避+抖动避免重试风暴。
- 仅在需要时组装与记录字段，日志包含必要指标便于监控与告警。
示例用法（简要）：
-
基本 GET：
$client = new RestHttpClient($logger);
$resp = $client->get('/users', ['page' => 1], [], ['base_uri' => 'https://api.example.com']);
$data = $resp->json();
-
POST JSON 并启用签名与自定义超时：
$client = new RestHttpClient($logger, new HmacSha256Signer($keyId, $secret), null, [], ['auto_sign' => true]);
$resp = $client->post('/orders', [], [
'base_uri' => 'https://api.vendor.com',
'json' => ['sku' => 'ABC', 'qty' => 2],
'timeout_ms' => 3000,
]);
-
文件上传（multipart）：
$file = new CURLFile('/path/to/file.pdf', 'application/pdf', 'contract.pdf');
$resp = $client->post('/upload', [], [
'base_uri' => 'https://files.example.com',
'multipart' => [
['name' => 'file', 'contents' => $file],
['name' => 'meta', 'contents' => json_encode(['category' => 'contract'])],
],
]);
