# HTTP客户端核心接口契约

**版本**: 1.0.0
**创建日期**: 2025-09-28
**目标**: 定义统一HTTP客户端的核心接口规范

## 接口定义

### IUniversalHttpClient

统一HTTP客户端的主接口，支持多平台账户的HTTP API调用。

```typescript
interface IUniversalHttpClient {
  /**
   * 执行HTTP请求
   * @param request 请求配置
   * @returns 响应数据
   */
  request<T = any>(request: HttpClientRequest): Promise<HttpClientResponse<T>>;

  /**
   * 批量执行HTTP请求
   * @param requests 请求配置数组
   * @returns 响应数据数组
   */
  batchRequest<T = any>(requests: HttpClientRequest[]): Promise<HttpClientResponse<T>[]>;

  /**
   * 注册新平台适配器
   * @param platform 平台名称
   * @param adapter 平台适配器实例
   */
  registerPlatform(platform: string, adapter: IPlatformAdapter): void;

  /**
   * 获取客户端健康状态
   * @returns 健康状态信息
   */
  getHealth(): Promise<HealthStatus>;

  /**
   * 关闭客户端，释放资源
   */
  close(): Promise<void>;
}
```

### HttpClientRequest

HTTP请求配置接口。

```typescript
interface HttpClientRequest {
  /** 目标交易平台 */
  platform: string;

  /** 账户标识符 */
  accountId: string;

  /** 请求方法 */
  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';

  /** 请求URL（相对路径） */
  url: string;

  /** 请求头 */
  headers?: Record<string, string>;

  /** 请求体 */
  body?: any;

  /** 请求选项 */
  options?: RequestOptions;
}
```

### RequestOptions

请求选项配置接口。

```typescript
interface RequestOptions {
  /** 超时配置 */
  timeout?: TimeoutConfig;

  /** 重试配置 */
  retry?: RetryConfig;

  /** 代理控制 */
  proxy?: ProxyControlOptions;

  /** 是否记录敏感数据 */
  logSensitiveData?: boolean;

  /** 幂等标识符 */
  idempotencyKey?: string;
}
```

### TimeoutConfig

超时配置接口。

```typescript
interface TimeoutConfig {
  /** 连接超时（毫秒） */
  connect?: number; // 默认5000

  /** 读取超时（毫秒） */
  read?: number;    // 默认30000

  /** 写入超时（毫秒） */
  write?: number;   // 默认15000
}
```

### RetryConfig

重试配置接口。

```typescript
interface RetryConfig {
  /** 最大重试次数 */
  maxAttempts?: number; // 默认3

  /** 重试延迟（毫秒） */
  delay?: number;       // 默认1000

  /** 是否使用指数退避 */
  exponentialBackoff?: boolean; // 默认true

  /** 重试条件判断 */
  shouldRetry?: (error: HttpClientError) => boolean;
}
```

### ProxyControlOptions

代理控制选项接口。

```typescript
interface ProxyControlOptions {
  /** 是否启用代理 */
  enabled?: boolean;

  /** 强制使用指定代理（覆盖全局和账户配置） */
  forceProxy?: ProxyConfig;

  /** 禁用代理（即使全局启用） */
  disableProxy?: boolean;

  /** 代理策略 */
  strategy?: 'global' | 'account' | 'force' | 'disabled';

  /** 代理轮换控制 */
  rotation?: {
    /** 是否启用轮换 */
    enabled?: boolean;
    /** 轮换间隔（请求数） */
    interval?: number;
    /** 轮换策略 */
    strategy?: 'round-robin' | 'random' | 'least-used';
  };

  /** 代理健康检查 */
  healthCheck?: {
    /** 是否启用健康检查 */
    enabled?: boolean;
    /** 检查超时（毫秒） */
    timeout?: number;
    /** 失败阈值 */
    failureThreshold?: number;
  };
}
```

### HttpClientResponse

HTTP响应接口。

```typescript
interface HttpClientResponse<T = any> {
  /** 响应状态码 */
  status: number;

  /** 响应状态文本 */
  statusText: string;

  /** 是否成功 */
  ok: boolean;

  /** 响应数据 */
  data: T;

  /** 响应头 */
  headers: Record<string, string>;

  /** 请求元信息 */
  metadata: ResponseMetadata;
}
```

### ResponseMetadata

响应元信息接口。

```typescript
interface ResponseMetadata {
  /** 请求ID */
  requestId: string;

  /** 执行时间（毫秒） */
  duration: number;

  /** 重试次数 */
  retryCount: number;

  /** 是否使用了代理 */
  usedProxy: boolean;

  /** 使用的代理URL */
  proxyUsed?: string;

  /** 时间戳 */
  timestamp: Date;

  /** 平台名称 */
  platform: string;
}
```

### HealthStatus

健康状态接口。

```typescript
interface HealthStatus {
  /** 整体状态 */
  status: 'healthy' | 'degraded' | 'unhealthy';

  /** 各平台状态 */
  platforms: Record<string, PlatformHealth>;

  /** 性能指标 */
  metrics: PerformanceMetrics;
}
```

### PlatformHealth

平台健康状态接口。

```typescript
interface PlatformHealth {
  /** 平台状态 */
  status: 'up' | 'down' | 'degraded';

  /** 响应时间（毫秒） */
  responseTime: number;

  /** 成功率（百分比） */
  successRate: number;

  /** 最后检查时间 */
  lastCheck: Date;
}
```

### PerformanceMetrics

性能指标接口。

```typescript
interface PerformanceMetrics {
  /** 总请求数 */
  totalRequests: number;

  /** 成功请求数 */
  successfulRequests: number;

  /** 平均响应时间（毫秒） */
  averageResponseTime: number;

  /** 99分位响应时间（毫秒） */
  p99ResponseTime: number;

  /** 活跃连接数 */
  activeConnections: number;
}
```

## 错误处理

### HttpClientError

HTTP客户端错误基类。

```typescript
class HttpClientError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly details?: any
  ) {
    super(message);
    this.name = 'HttpClientError';
  }
}
```

### 错误代码

| 错误代码 | 描述 | 重试建议 |
|----------|------|----------|
| `TIMEOUT` | 请求超时 | 重试 |
| `NETWORK_ERROR` | 网络错误 | 重试 |
| `AUTH_FAILED` | 认证失败 | 不重试 |
| `RATE_LIMITED` | 速率限制 | 延迟后重试 |
| `INVALID_REQUEST` | 无效请求 | 不重试 |
| `SERVER_ERROR` | 服务器错误 | 重试 |
| `PLATFORM_UNAVAILABLE` | 平台不可用 | 重试 |
| `PLATFORM_NOT_FOUND` | 平台未注册 | 不重试 |
| `PROXY_ERROR` | 代理连接失败 | 重试或切换代理 |

### ProxyConfig

增强的代理配置接口。

```typescript
interface ProxyConfig {
  /** 是否启用代理 */
  enabled: boolean;

  /** 代理URL */
  url?: string;

  /** 代理认证 */
  auth?: {
    username: string;
    password: string;
  };

  /** 代理类型 */
  type?: 'http' | 'https' | 'socks4' | 'socks5';

  /** 会话配置 */
  session?: {
    prefix: string;
    suffix: string;
    rotation: boolean;
    sticky?: boolean; // 会话是否粘性
  };

  /** 连接配置 */
  connection?: {
    /** 连接超时（毫秒） */
    timeout?: number;
    /** 保持连接 */
    keepAlive?: boolean;
    /** 最大空闲时间 */
    maxIdleTime?: number;
  };

  /** 代理池配置 */
  pool?: {
    /** 代理服务器列表 */
    servers: string[];
    /** 负载均衡策略 */
    strategy: 'round-robin' | 'random' | 'least-used' | 'fastest';
    /** 健康检查URL */
    healthCheckUrl?: string;
    /** 健康检查间隔（毫秒） */
    healthCheckInterval?: number;
  };

  /** 故障转移配置 */
  failover?: {
    /** 是否启用故障转移 */
    enabled: boolean;
    /** 最大重试次数 */
    maxRetries: number;
    /** 故障转移延迟（毫秒） */
    delay: number;
    /** 直连回退 */
    fallbackToDirect?: boolean;
  };
}
```

## 性能要求

### 响应时间
- 正常情况下：< 100ms
- 99分位数：< 200ms
- 超时阈值：30秒

### 并发能力
- 支持 >= 1000 并发请求
- 连接池大小：每平台20个连接
- 队列大小：每平台100个请求

### 可用性
- 目标可用性：99.9%
- 故障转移时间：< 5秒
- 恢复时间：< 30秒

## 安全要求

### 认证
- 集成 credential-manager 进行签名
- 支持多种签名算法（Ed25519, HMAC, EIP-191）
- 凭据隔离，防止账户间混淆

### 数据保护
- 敏感数据日志记录（可配置）
- 传输加密（HTTPS）
- 代理支持（用户配置）

### 审计
- 完整请求/响应日志
- 关联ID追踪
- 30天日志保留

---

**契约测试要求**: 所有接口必须有对应的契约测试，测试必须先失败后通过。