# HTTP客户端核心接口契约 **版本**: 1.0.0 **创建日期**: 2025-09-28 **目标**: 定义统一HTTP客户端的核心接口规范 ## 接口定义 ### IUniversalHttpClient 统一HTTP客户端的主接口，支持多平台账户的HTTP API调用。 ```typescript interface IUniversalHttpClient { /** * 执行HTTP请求 * @param request 请求配置 * @returns 响应数据 */ request(request: HttpClientRequest): Promise>; /** * 批量执行HTTP请求 * @param requests 请求配置数组 * @returns 响应数据数组 */ batchRequest(requests: HttpClientRequest[]): Promise[]>; /** * 注册新平台适配器 * @param platform 平台名称 * @param adapter 平台适配器实例 */ registerPlatform(platform: string, adapter: IPlatformAdapter): void; /** * 获取客户端健康状态 * @returns 健康状态信息 */ getHealth(): Promise; /** * 关闭客户端，释放资源 */ close(): Promise; } ``` ### HttpClientRequest HTTP请求配置接口。 ```typescript interface HttpClientRequest { /** 目标交易平台 */ platform: string; /** 账户标识符 */ accountId: string; /** 请求方法 */ method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'; /** 请求URL（相对路径） */ url: string; /** 请求头 */ headers?: Record; /** 请求体 */ 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 { /** 响应状态码 */ status: number; /** 响应状态文本 */ statusText: string; /** 是否成功 */ ok: boolean; /** 响应数据 */ data: T; /** 响应头 */ headers: Record; /** 请求元信息 */ 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; /** 性能指标 */ 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天日志保留 --- **契约测试要求**: 所有接口必须有对应的契约测试，测试必须先失败后通过。