import { AxiosRequestConfig, AxiosResponse } from 'axios'; import { HttpClientConfig } from '../interfaces/http-client-config.interface'; import { ApiKeyConfig, AuthType, BasicAuthConfig, BearerTokenConfig, CustomAuthConfig, OAuth2Config } from '../interfaces/api-client-config.interface'; import { HttpCircuitBreakerService } from './circuit-breaker.service'; import { HttpLoggingService } from './logging.service'; import { RedisLockService } from '../../redis-lock/redis-lock.service'; interface ExtendedAxiosRequestConfig extends AxiosRequestConfig { metadata?: { requestId?: string; startTime?: number; [key: string]: any; }; } /** * 请求级别配置选项 * 用于在单次请求中覆盖默认配置 */ export interface RequestOptions { /** 客户端名称 */ clientName?: string; /** 重试配置(请求级别,覆盖装饰器和全局配置) */ retry?: { enabled?: boolean; retries?: number; retryCondition?: (error: any) => boolean; retryDelay?: (retryCount: number) => number; shouldResetTimeout?: boolean; onRetry?: (retryCount: number, error: any, requestConfig: any) => void; }; /** 返回类型: 'data'(默认) | 'full' | 'custom' */ returnType?: 'data' | 'full' | 'custom'; /** 自定义返回转换函数 */ transform?: (response: AxiosResponse) => any; } /** * 认证配置接口 */ interface AuthConfig { type: AuthType; config?: ApiKeyConfig | BasicAuthConfig | BearerTokenConfig | OAuth2Config | CustomAuthConfig; } /** * HTTP客户端服务 * 基于Spring RestTemplate的设计理念,集成axios-retry库 * 支持两种创建模式: * 1. 直接创建: 用于简单的HTTP请求场景 * 2. API客户端模式: 用于需要认证、统计等高级功能的API客户端 */ export declare class HttpClientService { private readonly circuitBreakerService; private readonly loggingService; private readonly redisLockService?; private readonly logger; private readonly axiosInstance; private readonly defaultConfig; private readonly authConfig?; private readonly clientName?; private requestStats; constructor(circuitBreakerService: HttpCircuitBreakerService, loggingService: HttpLoggingService, redisLockService?: RedisLockService, config?: HttpClientConfig, clientName?: string, authConfig?: AuthConfig); /** * 静态工厂方法:创建API客户端模式的 HttpClientService * @param dependencies 依赖服务 * @param config API客户端配置 * @returns HttpClientService 实例 */ static createApiClient(dependencies: { circuitBreakerService: HttpCircuitBreakerService; loggingService: HttpLoggingService; redisLockService?: RedisLockService; }, config: { name: string; baseURL?: string; timeout?: number; httpConfig?: HttpClientConfig; auth?: AuthConfig; }): HttpClientService; /** * 执行HTTP请求 * @param config 请求配置 * @param options 请求级别配置选项 * @returns 响应数据 * * @example * // 禁用重试 * await this.request({ url: '/api/data' }, { retry: { enabled: false } }) * * @example * // 完整配置 * await this.request({ url: '/api/data' }, { * clientName: 'api-client', * retry: { enabled: true, retries: 2 }, * timeout: 5000, * returnType: 'full' * }) */ request(config: ExtendedAxiosRequestConfig, options?: RequestOptions): Promise; /** * 生成curl命令(动态生成,不存储) */ generateCurlCommand(config: ExtendedAxiosRequestConfig): string; /** * 生成调试curl命令(动态生成,不存储) */ generateDebugCurlCommand(config: ExtendedAxiosRequestConfig, response?: AxiosResponse): string; /** * 获取请求统计信息 */ getStats(): any; /** * 重置统计信息 */ resetStats(): void; /** * 获取客户端名称 */ getName(): string | undefined; get(url: string, config?: AxiosRequestConfig, options?: RequestOptions): Promise; post(url: string, data?: any, config?: AxiosRequestConfig, options?: RequestOptions): Promise; put(url: string, data?: any, config?: AxiosRequestConfig, options?: RequestOptions): Promise; patch(url: string, data?: any, config?: AxiosRequestConfig, options?: RequestOptions): Promise; delete(url: string, config?: AxiosRequestConfig, options?: RequestOptions): Promise; /** * 带等待锁的认证请求方法 * 用于需要确保只有一个进程执行认证相关操作的场景 * * @param config 请求配置 * @param tokenProvider token提供函数 * @param lockOptions 等待锁选项 * @param requestOptions HTTP请求选项 * @returns 响应数据 */ authRequest(config: AxiosRequestConfig, tokenProvider: () => Promise, lockOptions?: { lockKey?: string; lockTimeout?: number; waitTimeout?: number; enableRetry?: boolean; }, requestOptions?: RequestOptions): Promise; /** * 带等待锁的批量认证请求 * 用于需要批量执行认证相关操作但避免重复认证的场景 * * @param requests 请求数组 * @param tokenProvider token提供函数 * @param options 等待锁选项 * @returns 响应数组 */ authBatchRequest(requests: Array<{ config: AxiosRequestConfig; key: string; }>, tokenProvider: () => Promise, lockOptions?: { lockKey?: string; lockTimeout?: number; waitTimeout?: number; maxConcurrency?: number; }, requestOptions?: RequestOptions): Promise>; /** * Capture calling context information * @returns Calling context with service class and method name */ private captureCallingContext; private shouldLogToDatabase; private createBearerAuthConfig; /** * 创建Axios实例并配置axios-retry */ private createAxiosInstance; /** * 执行带特性的请求(重试、熔断器等) * 返回响应和熔断器状态 */ private executeWithFeatures; private resolveRetryConfig; private createAxiosRetryConfig; private defaultRetryCondition; /** * 计算重试延迟 */ private calculateRetryDelay; /** * 应用装饰器配置 * 只在装饰器配置值有效时才覆盖请求配置 */ private applyDecoratorConfig; /** * 生成熔断器键 */ private generateCircuitBreakerKey; /** * 合并默认配置 */ private mergeWithDefaults; /** * 深度合并对象 * 只在源值有效(非 undefined)时才覆盖目标值 */ private deepMerge; /** * 解析代理配置 * 支持从环境变量或手动配置中读取 * @param proxyConfig 代理配置 * @param targetUrl 目标 URL(用于 NO_PROXY 检查) * @returns 解析后的代理配置,如果不应使用代理则返回 false 或 undefined */ private resolveProxyConfig; /** * 应用认证配置到请求配置 */ private applyAuthToConfig; /** * 更新请求统计信息 * 统一管理所有统计,避免在拦截器中重复统计 */ private updateRequestStats; } export {};