@nest-omni/core 4.1.3-3 → 4.1.3-30

package/http-client/services/circuit-breaker.service.d.ts

@@ -1,5 +1,16 @@
 import { Logger } from '@nestjs/common';
 import { CircuitBreakerConfig } from '../interfaces/http-client-config.interface';
+/**
+ * Circuit Breaker 清理配置
+ */
+interface CircuitBreakerCleanupConfig {
+    /** 最大空闲时间（毫秒），超过此时间未使用的circuit breaker将被清理 */
+    maxIdleTimeMs: number;
+    /** 清理间隔（毫秒），定期清理的时间间隔 */
+    cleanupIntervalMs: number;
+    /** 最大circuit breaker数量，超过此数量时触发LRU清理 */
+    maxSize: number;
+}
 /**
  * 熔断器服务
  * 基于Spring Cloud CircuitBreaker的设计理念
@@ -7,6 +18,11 @@ import { CircuitBreakerConfig } from '../interfaces/http-client-config.interface
 export declare class HttpCircuitBreakerService {
     private readonly logger;
     private readonly circuitBreakers;
+    private cleanupTimer?;
+    /** 默认清理配置 */
+    private readonly cleanupConfig;
+    constructor();
+    onModuleDestroy(): void;
     /**
      * 获取或创建熔断器
      */
@@ -14,7 +30,11 @@ export declare class HttpCircuitBreakerService {
     /**
      * 执行带熔断保护的请求
      */
-    executeWithCircuitBreaker<T>(key: string, requestFn: () => Promise<T>, config: CircuitBreakerConfig): Promise<T>;
+    executeWithCircuitBreaker<T>(key: string, requestFn: () => Promise<T>, config: CircuitBreakerConfig, onStateChange?: (state: string) => void): Promise<T>;
+    /**
+     * 获取熔断器当前状态
+     */
+    getCircuitBreakerState(key: string): string | undefined;
     /**
      * 重置所有熔断器
      */
@@ -23,6 +43,39 @@ export declare class HttpCircuitBreakerService {
      * 获取所有熔断器状态
      */
     getAllStates(): Record<string, any>;
+    /**
+     * 获取Circuit Breaker统计信息
+     */
+    getStats(): {
+        total: number;
+        byState: Record<string, number>;
+    };
+    /**
+     * 清理空闲的Circuit Breaker
+     * 清理超过最大空闲时间的Circuit Breaker
+     */
+    cleanupIdle(): number;
+    /**
+     * 手动触发清理（用于测试）
+     */
+    manualCleanup(): number;
+    /**
+     * 设置清理配置
+     */
+    setCleanupConfig(config: Partial<CircuitBreakerCleanupConfig>): void;
+    /**
+     * 获取清理配置
+     */
+    getCleanupConfig(): CircuitBreakerCleanupConfig;
+    /**
+     * 基于LRU策略清理Circuit Breaker
+     * 删除最久未访问的Circuit Breaker直到数量降到maxSize以下
+     */
+    private cleanupLRU;
+    /**
+     * 启动定期清理任务
+     */
+    private startCleanupTask;
 }
 /**
  * 熔断器类
@@ -38,11 +91,21 @@ declare class CircuitBreaker {
     private nextAttemptTime;
     private requestCount;
     private windowStartTime;
+    private onStateChange?;
+    private lastAccessTime;
     constructor(key: string, config: CircuitBreakerConfig, logger: Logger);
+    /**
+     * 更新最后访问时间
+     */
+    updateLastAccessTime(): void;
+    /**
+     * 获取最后访问时间
+     */
+    getLastAccessTime(): number;
     /**
      * 执行请求
      */
-    execute<T>(requestFn: () => Promise<T>): Promise<T>;
+    execute<T>(requestFn: () => Promise<T>, onStateChange?: (state: string) => void): Promise<T>;
     /**
      * 重置熔断器
      */
@@ -71,6 +134,10 @@ declare class CircuitBreaker {
      * 转换到半开状态
      */
     private transitionToHalfOpen;
+    /**
+     * 通知状态变化
+     */
+    private notifyStateChange;
     /**
      * 重置监控窗口
      */

package/http-client/services/circuit-breaker.service.js

@@ -5,6 +5,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -35,25 +38,70 @@ let HttpCircuitBreakerService = HttpCircuitBreakerService_1 = class HttpCircuitB
     constructor() {
         this.logger = new common_1.Logger(HttpCircuitBreakerService_1.name);
         this.circuitBreakers = new Map();
+        /** 默认清理配置 */
+        this.cleanupConfig = {
+            maxIdleTimeMs: 30 * 60 * 1000, // 30分钟
+            cleanupIntervalMs: 5 * 60 * 1000, // 5分钟
+            maxSize: 1000, // 最多1000个circuit breaker
+        };
+        // 启动定期清理任务
+        this.startCleanupTask();
+    }
+    onModuleDestroy() {
+        // 清理定时器
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+        }
     }
     /**
      * 获取或创建熔断器
      */
     getCircuitBreaker(key, config) {
-        if (!this.circuitBreakers.has(key)) {
-            this.circuitBreakers.set(key, new CircuitBreaker(key, config, this.logger));
+        let circuitBreaker = this.circuitBreakers.get(key);
+        if (!circuitBreaker) {
+            this.logger.debug(`Creating new circuit breaker with key: ${key}`);
+            circuitBreaker = new CircuitBreaker(key, config, this.logger);
+            this.circuitBreakers.set(key, circuitBreaker);
+            // 检查是否超过最大数量，如果是则触发LRU清理
+            if (this.circuitBreakers.size > this.cleanupConfig.maxSize) {
+                this.cleanupLRU();
+            }
+        }
+        else {
+            this.logger.debug(`Reusing existing circuit breaker with key: ${key}`);
+            // 更新最后访问时间
+            circuitBreaker.updateLastAccessTime();
         }
-        return this.circuitBreakers.get(key);
+        return circuitBreaker;
     }
     /**
      * 执行带熔断保护的请求
      */
-    executeWithCircuitBreaker(key, requestFn, config) {
+    executeWithCircuitBreaker(key, requestFn, config, onStateChange) {
         return __awaiter(this, void 0, void 0, function* () {
             const circuitBreaker = this.getCircuitBreaker(key, config);
-            return circuitBreaker.execute(requestFn);
+            return circuitBreaker.execute(requestFn, onStateChange);
         });
     }
+    /**
+     * 获取熔断器当前状态
+     */
+    getCircuitBreakerState(key) {
+        // Log all current circuit breaker keys for debugging
+        this.logger.debug(`Looking for circuit breaker key: ${key}. Available keys: [${Array.from(this.circuitBreakers.keys()).join(', ')}]`);
+        const circuitBreaker = this.circuitBreakers.get(key);
+        if (!circuitBreaker) {
+            this.logger.debug(`Circuit breaker not found for key: ${key}`);
+            return undefined;
+        }
+        const state = circuitBreaker.getState();
+        if (!state) {
+            this.logger.debug(`Circuit breaker getState() returned undefined for key: ${key}`);
+            return undefined;
+        }
+        this.logger.debug(`Circuit breaker state for ${key}: ${state.state}`);
+        return state.state;
+    }
     /**
      * 重置所有熔断器
      */
@@ -70,10 +118,111 @@ let HttpCircuitBreakerService = HttpCircuitBreakerService_1 = class HttpCircuitB
         });
         return states;
     }
+    /**
+     * 获取Circuit Breaker统计信息
+     */
+    getStats() {
+        const stats = {
+            total: this.circuitBreakers.size,
+            byState: {
+                CLOSED: 0,
+                OPEN: 0,
+                HALF_OPEN: 0,
+            },
+        };
+        this.circuitBreakers.forEach((cb) => {
+            const state = cb.getState();
+            if (state && state.state) {
+                stats.byState[state.state]++;
+            }
+        });
+        return stats;
+    }
+    /**
+     * 清理空闲的Circuit Breaker
+     * 清理超过最大空闲时间的Circuit Breaker
+     */
+    cleanupIdle() {
+        const now = Date.now();
+        const keysToDelete = [];
+        this.circuitBreakers.forEach((cb, key) => {
+            const lastAccess = cb.getLastAccessTime();
+            if (now - lastAccess > this.cleanupConfig.maxIdleTimeMs) {
+                keysToDelete.push(key);
+            }
+        });
+        keysToDelete.forEach((key) => {
+            this.circuitBreakers.delete(key);
+            this.logger.debug(`Removed idle circuit breaker: ${key}`);
+        });
+        if (keysToDelete.length > 0) {
+            this.logger.log(`Cleaned up ${keysToDelete.length} idle circuit breaker(s)`);
+        }
+        return keysToDelete.length;
+    }
+    /**
+     * 手动触发清理（用于测试）
+     */
+    manualCleanup() {
+        return this.cleanupIdle();
+    }
+    /**
+     * 设置清理配置
+     */
+    setCleanupConfig(config) {
+        Object.assign(this.cleanupConfig, config);
+        // 重启清理任务
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+        }
+        this.startCleanupTask();
+        this.logger.log(`Circuit breaker cleanup config updated: ${JSON.stringify(this.cleanupConfig)}`);
+    }
+    /**
+     * 获取清理配置
+     */
+    getCleanupConfig() {
+        return Object.assign({}, this.cleanupConfig);
+    }
+    /**
+     * 基于LRU策略清理Circuit Breaker
+     * 删除最久未访问的Circuit Breaker直到数量降到maxSize以下
+     */
+    cleanupLRU() {
+        const entries = Array.from(this.circuitBreakers.entries());
+        // 按最后访问时间排序（最老的在前）
+        entries.sort((a, b) => {
+            return a[1].getLastAccessTime() - b[1].getLastAccessTime();
+        });
+        // 计算需要删除的数量
+        const toDelete = entries.slice(0, entries.length - this.cleanupConfig.maxSize);
+        toDelete.forEach(([key]) => {
+            this.circuitBreakers.delete(key);
+            this.logger.debug(`Removed LRU circuit breaker: ${key}`);
+        });
+        if (toDelete.length > 0) {
+            this.logger.warn(`LRU cleanup: removed ${toDelete.length} circuit breaker(s) to maintain max size of ${this.cleanupConfig.maxSize}`);
+        }
+    }
+    /**
+     * 启动定期清理任务
+     */
+    startCleanupTask() {
+        this.cleanupTimer = setInterval(() => {
+            try {
+                this.cleanupIdle();
+            }
+            catch (error) {
+                this.logger.error('Error during circuit breaker cleanup', error);
+            }
+        }, this.cleanupConfig.cleanupIntervalMs);
+        this.logger.log(`Circuit breaker cleanup task started (interval: ${this.cleanupConfig.cleanupIntervalMs}ms, maxIdleTime: ${this.cleanupConfig.maxIdleTimeMs}ms)`);
+    }
 };
 exports.HttpCircuitBreakerService = HttpCircuitBreakerService;
 exports.HttpCircuitBreakerService = HttpCircuitBreakerService = HttpCircuitBreakerService_1 = __decorate([
-    (0, common_1.Injectable)()
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [])
 ], HttpCircuitBreakerService);
 /**
  * 熔断器类
@@ -90,12 +239,27 @@ class CircuitBreaker {
         this.nextAttemptTime = 0;
         this.requestCount = 0;
         this.windowStartTime = Date.now();
+        this.lastAccessTime = Date.now(); // 添加最后访问时间跟踪
+    }
+    /**
+     * 更新最后访问时间
+     */
+    updateLastAccessTime() {
+        this.lastAccessTime = Date.now();
+    }
+    /**
+     * 获取最后访问时间
+     */
+    getLastAccessTime() {
+        return this.lastAccessTime;
     }
     /**
      * 执行请求
      */
-    execute(requestFn) {
+    execute(requestFn, onStateChange) {
         return __awaiter(this, void 0, void 0, function* () {
+            // 保存状态变化回调
+            this.onStateChange = onStateChange;
             const currentTime = Date.now();
             // 检查是否需要重置监控窗口
             if (currentTime - this.windowStartTime > this.config.monitoringPeriodMs) {
@@ -197,6 +361,8 @@ class CircuitBreaker {
             this.state = CircuitBreakerState.CLOSED;
             this.failureCount = 0;
             this.successCount = 0;
+            // 通知状态变化
+            this.notifyStateChange(CircuitBreakerState.CLOSED);
         }
     }
     /**
@@ -208,6 +374,8 @@ class CircuitBreaker {
             this.state = CircuitBreakerState.OPEN;
             this.nextAttemptTime = Date.now() + this.config.recoveryTimeoutMs;
             this.successCount = 0;
+            // 通知状态变化
+            this.notifyStateChange(CircuitBreakerState.OPEN);
         }
     }
     /**
@@ -218,6 +386,16 @@ class CircuitBreaker {
             this.logger.log(`Circuit breaker ${this.key} transitioned to HALF_OPEN`);
             this.state = CircuitBreakerState.HALF_OPEN;
             this.successCount = 0;
+            // 通知状态变化
+            this.notifyStateChange(CircuitBreakerState.HALF_OPEN);
+        }
+    }
+    /**
+     * 通知状态变化
+     */
+    notifyStateChange(state) {
+        if (this.onStateChange) {
+            this.onStateChange(state);
         }
     }
     /**

package/http-client/services/http-client.service.d.ts

@@ -1,8 +1,8 @@
 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 { HttpCacheService } from './cache.service';
 import { RedisLockService } from '../../redis-lock/redis-lock.service';
 interface ExtendedAxiosRequestConfig extends AxiosRequestConfig {
     metadata?: {
@@ -11,24 +11,69 @@ interface ExtendedAxiosRequestConfig extends AxiosRequestConfig {
         [key: string]: any;
     };
 }
+/**
+ * 请求返回选项
+ */
+interface RequestReturnOptions {
+    /** 返回类型: '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 cacheService;
     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, cacheService: HttpCacheService, redisLockService?: RedisLockService, config?: HttpClientConfig);
+    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 decoratorContext 装饰器上下文
+     * @param clientName 客户端名称
+     * @param returnOptions 返回选项
+     *   - returnType: 'data'(默认)只返回response.data
+     *   - returnType: 'full'返回完整AxiosResponse对象
+     *   - returnType: 'custom'使用自定义转换函数
+     *   - transform: 自定义转换函数，接收完整response返回任意数据
      */
-    request<T = any>(config: ExtendedAxiosRequestConfig, decoratorContext?: any): Promise<T>;
+    request<T = any>(config: ExtendedAxiosRequestConfig, decoratorContext?: any, clientName?: string, returnOptions?: RequestReturnOptions): Promise<T>;
     /**
      * 生成curl命令（动态生成，不存储）
      */
@@ -45,11 +90,15 @@ export declare class HttpClientService {
      * 重置统计信息
      */
     resetStats(): void;
-    get<T = any>(url: string, config?: AxiosRequestConfig): Promise<T>;
-    post<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
-    put<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
-    patch<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
-    delete<T = any>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * 获取客户端名称
+     */
+    getName(): string | undefined;
+    get<T = any>(url: string, config?: AxiosRequestConfig, clientName?: string, returnOptions?: RequestReturnOptions): Promise<T>;
+    post<T = any>(url: string, data?: any, config?: AxiosRequestConfig, clientName?: string, returnOptions?: RequestReturnOptions): Promise<T>;
+    put<T = any>(url: string, data?: any, config?: AxiosRequestConfig, clientName?: string, returnOptions?: RequestReturnOptions): Promise<T>;
+    patch<T = any>(url: string, data?: any, config?: AxiosRequestConfig, clientName?: string, returnOptions?: RequestReturnOptions): Promise<T>;
+    delete<T = any>(url: string, config?: AxiosRequestConfig, clientName?: string, returnOptions?: RequestReturnOptions): Promise<T>;
     /**
      * 带等待锁的认证请求方法
      * 用于需要确保只有一个进程执行认证相关操作的场景
@@ -64,7 +113,7 @@ export declare class HttpClientService {
         lockTimeout?: number;
         waitTimeout?: number;
         enableRetry?: boolean;
-    }): Promise<T>;
+    }, clientName?: string, returnOptions?: RequestReturnOptions): Promise<T>;
     /**
      * 带等待锁的批量认证请求
      * 用于需要批量执行认证相关操作但避免重复认证的场景
@@ -82,13 +131,19 @@ export declare class HttpClientService {
         lockTimeout?: number;
         waitTimeout?: number;
         maxConcurrency?: number;
-    }): Promise<Array<T | null>>;
+    }, clientName?: string): Promise<Array<T | null>>;
+    /**
+     * Capture calling context information
+     * @returns Calling context with service class and method name
+     */
+    private captureCallingContext;
     /**
      * 创建Axios实例并配置axios-retry
      */
     private createAxiosInstance;
     /**
      * 执行带特性的请求（重试、熔断器等）
+     * 返回响应和熔断器状态
      */
     private executeWithFeatures;
     /**
@@ -97,31 +152,38 @@ export declare class HttpClientService {
     private calculateRetryDelay;
     /**
      * 应用装饰器配置
+     * 只在装饰器配置值有效时才覆盖请求配置
      */
     private applyDecoratorConfig;
-    /**
-     * 判断是否应该缓存请求
-     */
-    private shouldCacheRequest;
     /**
      * 生成熔断器键
      */
     private generateCircuitBreakerKey;
-    /**
-     * 更新请求统计
-     */
-    private updateStats;
-    /**
-     * 更新错误统计
-     */
-    private updateErrorStats;
     /**
      * 合并默认配置
      */
     private mergeWithDefaults;
     /**
      * 深度合并对象
+     * 只在源值有效（非 undefined）时才覆盖目标值
      */
     private deepMerge;
+    /**
+     * 解析代理配置
+     * 支持从环境变量或手动配置中读取
+     * @param proxyConfig 代理配置
+     * @param targetUrl 目标 URL（用于 NO_PROXY 检查）
+     * @returns 解析后的代理配置，如果不应使用代理则返回 false 或 undefined
+     */
+    private resolveProxyConfig;
+    /**
+     * 应用认证配置到请求配置
+     */
+    private applyAuthToConfig;
+    /**
+     * 更新请求统计信息
+     * 统一管理所有统计,避免在拦截器中重复统计
+     */
+    private updateRequestStats;
 }
 export {};