HTTP客户端核心接口契约

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

接口定义

IUniversalHttpClient

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

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请求配置接口。

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

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

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

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

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

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

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

RequestOptions

请求选项配置接口。

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

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

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

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

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

TimeoutConfig

超时配置接口。

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

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

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

RetryConfig

重试配置接口。

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

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

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

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

ProxyControlOptions

代理控制选项接口。

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响应接口。

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

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

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

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

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

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

ResponseMetadata

响应元信息接口。

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

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

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

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

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

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

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

HealthStatus

健康状态接口。

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

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

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

PlatformHealth

平台健康状态接口。

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

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

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

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

PerformanceMetrics

性能指标接口。

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

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

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

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

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

错误处理

HttpClientError

HTTP客户端错误基类。

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

增强的代理配置接口。

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天日志保留

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

http-client.contract.md 8.0 KB History Raw